> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vouchersx.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks overview

> Outbound HTTP POSTs the Voucher Platform sends to your webhookUrl.

We POST JSON to your `webhookUrl` whenever a user-relevant event happens.

## Event types

| Event                | When                                                       | Notes                                                       |
| -------------------- | ---------------------------------------------------------- | ----------------------------------------------------------- |
| `CLAIM_CREATED`      | User adds a wallet-flow voucher.                           | Fires from `POST /me/claims`.                               |
| `REDEMPTION_CREATED` | User redeems a voucher at an outlet (SUCCESS or FLAGGED).  | The bread-and-butter event most partners care about.        |
| `VOUCHER_PUBLISHED`  | A merchant the user has favorited publishes a new voucher. | Fanned out at publish time — one event per favoriting user. |

### Events *not* delivered to partner webhooks

A few internal events flow through the same notification table but **never
reach your `webhookUrl`**:

| Event                                     | Why not                                                                                                                                                                                                                             |
| ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `FAVORITE_CREATED`                        | Not part of the partner contract. If you need to know when your users favorite merchants, call `GET /me/favorites` from the webview.                                                                                                |
| `VOUCHER_EXPIRED` / `VOUCHER_UNPUBLISHED` | Voucher-level signals (no `recipient_user_id`). Partners that need them can subscribe to a dedicated polling endpoint — talk to us if you have a use case. Today they exist only so the internal admin / main-app can clean caches. |

## Envelope

Every webhook shares the same outer shape:

```jsonc theme={null}
{
  "id": "9f1a2c4d-5e6f-7891-a2b3-c4d5e6f78901",   // event UUID. Use for idempotency.
  "type": "REDEMPTION_CREATED",                     // see table above
  "createdAt": "2026-05-12T08:14:22.501Z",          // when the event row was written
  "data": {
    "userId": "8d2a7f3b-...",                       // our internal user ID
    "externalUserId": "usr_demo_001",               // your external ID (always present for partner users)
    // ... event-specific fields ...
  }
}
```

## Headers

| Header         | Value                                                                                                                         |
| -------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `content-type` | `application/json`                                                                                                            |
| `x-event-id`   | Same as `body.id`. Useful for log correlation before parsing the body.                                                        |
| `x-event-type` | Same as `body.type`. Lets you route without parsing.                                                                          |
| `x-signature`  | `t=<unix>,v1=<hex>` — HMAC over the **raw body**, same algorithm as inbound. See [HMAC authentication](/authentication/hmac). |

## Where to go next

<CardGroup cols={2}>
  <Card title="Event payloads" icon="brackets-curly" href="/webhooks/payloads">
    The full payload shape for each event type, with a verification snippet.
  </Card>

  <Card title="Delivery semantics" icon="repeat" href="/webhooks/delivery">
    Retry schedule, idempotency, receiver checklist.
  </Card>
</CardGroup>