# GOV.UK Pay Webhooks

Receive GOV.UK Pay card-payment updates.

## When to Use This Skill

* Configure a receiver for GOV.UK Pay webhook deliveries.
* Diagnose `pay-signature` verification failures.
* Handle `card_payment_captured`, `card_payment_succeeded`, `card_payment_refunded`.

## Setup

In the GOV.UK Pay admin tool, open Settings > Developers > Webhooks, configure the endpoint and events, and use View to reveal this webhook's signing secret. Live callbacks require HTTPS with TLS 1.2 and a .gov.uk domain. Exceptions require support approval and a domain owned by your service or parent organisation. Use public tunnel URLs only for sandbox or not-live-yet testing; confirm an approved callback domain before live Hookdeck routing.

Set `GOVUK_PAY_WEBHOOK_SECRET` in the server environment. Read [setup](https://github.com/hookdeck/webhook-skills/blob/main/skills/govuk-pay-webhooks/references/setup.md) before enabling delivery.

## Verification (core)

`pay-signature` contains a bare hex digest over the raw body. Use HMAC-SHA256 with the secret's UTF-8 bytes. Verify the original bytes before parsing JSON. Validate the digest format, then compare equal-length buffers in constant time.

After extracting the documented digest and constructing `message` as described in [verification](https://github.com/hookdeck/webhook-skills/blob/main/skills/govuk-pay-webhooks/references/verification.md), the comparison is:

```javascript
const expected = crypto.createHmac('sha256', secret).update(message).digest();
if (digest.length !== 64 || !/^[0-9a-fA-F]{64}$/.test(digest)) return false;
const received = Buffer.from(digest, 'hex');
return received.length === expected.length && crypto.timingSafeEqual(received, expected);

```

No timestamp is included in the signed message. These examples do not invent an age check from unsigned fields.

Complete handlers and tests: [Express](https://github.com/hookdeck/webhook-skills/tree/main/skills/govuk-pay-webhooks/examples/express/), [Next.js](https://github.com/hookdeck/webhook-skills/tree/main/skills/govuk-pay-webhooks/examples/nextjs/), [FastAPI](https://github.com/hookdeck/webhook-skills/tree/main/skills/govuk-pay-webhooks/examples/fastapi/).

## Event Handling

Read event_type from the body. webhook_message_id identifies the message. Verify Pay-Signature with the signing secret as UTF-8 bytes, preserving the body bytes exactly without adding a BOM.

Return 2xx promptly. Messages may arrive more than once and out of order; deduplicate using webhook_message_id and reconcile payment state before applying updates.

## Local Development

```bash
npx hookdeck-cli listen 3000 govuk-pay --path /webhooks/govuk-pay

```

Use port 8000 for FastAPI. The CLI provides a local tunnel and inspection UI; no account is required to start.

## Resources

* [Overview and event routing](https://github.com/hookdeck/webhook-skills/blob/main/skills/govuk-pay-webhooks/references/overview.md)
* [Endpoint and secret setup](https://github.com/hookdeck/webhook-skills/blob/main/skills/govuk-pay-webhooks/references/setup.md)
* [Verification and troubleshooting](https://github.com/hookdeck/webhook-skills/blob/main/skills/govuk-pay-webhooks/references/verification.md)