---
title: Receive partner webhooks
description: Verify, persist, and reconcile signed partner event deliveries.
sidebar:
  order: 5.375
---

Partner event delivery is configured separately for each organization and
mode. Creating a subscription or replaying a delivery requires its current
delivery configuration. Existing scoped event reads, delivery visibility and
revocation remain available when outbound delivery is disabled. Use the
[polling guide](/polling) for current deposit and order facts. A
contract shape or a local test is not evidence that a receiver, carrier,
provider, or hosted environment accepts an event.

When configured, the event stream contains customer-safe changes only:

- `deposit.assessed`
- `deposit.accepted`
- `order.shipped`
- `order.cancelled`

An event is not a physical-picking, carrier-handoff, delivery, or tokenization
confirmation. In particular, `deposit.assessed` has no readiness or mint
field. Read the factual deposit result when your platform needs the current
accepted units.

## Configure one receiver

Create a receiver with `POST
/v1/organizations/{orgId}/partner-events/subscriptions` or MCP
`partner_events_subscriptions_create`. Its body contains only the receiver's
public HTTPS `url` on port 443, without embedded credentials:

```json title="example:partner-event-subscription"
{
  "url": "https://events.example.com/vault"
}
```

Vault does not follow redirects. The HTTP result contains
`data.subscription`, with `subscriptionId`, `url`, `createdAt` and `revokedAt`.
A null `revokedAt` means active. It never returns a signing secret.

Use `GET /v1/organizations/{orgId}/partner-events/subscriptions/{subscriptionId}`
or MCP `partner_events_subscriptions_get` to inspect it. `DELETE` on that
same path or MCP `partner_events_subscriptions_revoke` revokes it. Revocation
stops its pending deliveries; it does not erase the business events or a
receiver's durable ingestion record.

Vault rechecks the active delivery claim immediately before network dispatch.
A request that has already been admitted may still arrive after revocation;
revocation cannot retract an in-flight request. Keep ingestion idempotent and
reconcile current facts when an older delivery arrives.

## Verify the raw delivery

### Test captures

Configured Test delivery writes a private Test capture instead of contacting
the receiver. Its delivery outcome is `captured`, with `capturedAt` and no
receiver HTTP status or acknowledgement. It performs no DNS lookup or HTTPS
request and requires no Live signing key. A replay retains the same event and
capture identity; it does not repeat a business effect. Test capture proves
the configured Test path only. Verify real signed delivery separately before
relying on a receiver in Live.

### Live signatures

Vault sends a `POST` whose raw JSON bytes are the event envelope. Before JSON
parsing, persistence, deduplication, or a business effect, calculate an
HMAC-SHA256 over those exact bytes with the signing key configured for the
receiver. Compare the result in constant time with `x-vault-event-signature`,
whose value is `sha256=<lowercase-hex-digest>`. Do not parse and reserialize
the body before verification.

Vault also sends these headers:

| Header | Required check |
| --- | --- |
| `x-vault-event-id` | Equals the body `id`. |
| `x-vault-event-version` | Equals the body `version` as a string. Version 1 is the current contract. |
| `x-vault-event-signature` | Exact raw-body HMAC-SHA256 verification succeeds. |

Reject a delivery that fails any check. This contract has no signed attempt
timestamp or freshness header: do not invent a time-window guarantee. After
verification, validate the versioned event shape and scope it to the
organization and mode your receiver serves. A valid signature never grants
access to a different organization or mode.

## Store before acknowledging

The complete HTTP poll result has `data` plus `meta.requestId`. Each entry in
`data.items` is the raw event object used for webhook delivery. This is a version 1
`deposit.accepted` event inside a poll response:

```json title="example:partner-event-page"
{
  "data": {
    "checkpoint": 42,
    "items": [
      {
        "data": {
          "acceptance": {
            "items": [
              {
                "assessedCondition": "lp",
                "productId": "product_variant_demo",
                "quantity": 1,
                "receiptLineId": "receipt_line_demo",
                "revision": 2,
                "unitRefs": ["receipt_line_demo:0"],
                "variantSku": {
                  "kind": "available",
                  "value": "CARD-DEMO-LP"
                }
              }
            ],
            "kind": "current",
            "revision": 3
          },
          "assessment": [
            {
              "assessedCondition": "lp",
              "productId": "product_variant_demo",
              "quantity": 1,
              "receiptLineId": "receipt_line_demo",
              "revision": 2,
              "unitRefs": ["receipt_line_demo:0"],
              "variantSku": {
                "kind": "available",
                "value": "CARD-DEMO-LP"
              }
            }
          ],
          "declarationRevision": 2,
          "depositRef": "deposit_demo_1",
          "purchaseOrderId": "00000000-0000-4000-8000-000000000001"
        },
        "entity": {
          "id": "00000000-0000-4000-8000-000000000001",
          "kind": "deposit",
          "revision": "deposit-event-7"
        },
        "id": "f4c96a75-e955-4602-a22a-166ba9d224e3",
        "occurredAt": "2026-11-05T23:00:00.000Z",
        "scope": {
          "mode": "live",
          "organizationId": "org_example"
        },
        "sequence": 42,
        "type": "deposit.accepted",
        "version": 1
      }
    ]
  },
  "meta": { "requestId": "req_example" }
}
```

After verification, use `{ scope.organizationId, scope.mode, id }` as the
durable idempotency key. Store the event and any downstream decision
transactionally before returning a `2xx`. Deliveries can be duplicated or
arrive out of order, including after a successful response was lost. The same
business event retains its ID when redelivered or replayed.

`sequence` is the strictly advancing checkpoint for one scope. It orders the
stream but does not replace the event ID for deduplication. `entity.revision`
identifies that entity change; it is not a stream position. For deposits,
`data.acceptance.revision` is a distinct accepted-snapshot revision. A dispute
release can change accepted units without changing that acceptance revision,
so reconcile the factual items and stable `unitRefs` rather than skipping an
event because a revision value is unchanged. A changed count-line revision
also does not create a new card identity.

## Catch up with polling

Use `GET /v1/organizations/{orgId}/partner-events?after=<checkpoint>&limit=<limit>`
or MCP `partner_events_list` for recovery and normal reconciliation. `limit`
is 1 through 100. Process returned events in ascending `sequence`, then save
`data.checkpoint` only after every event in the page has been durably handled.
If processing fails, retain the prior checkpoint and request the page again.
An empty page leaves the checkpoint unchanged. `meta.requestId` identifies the
HTTP request for support; it is not a stream checkpoint.

Request the next page with its returned checkpoint until a page has no items.
Polling returns the same facts as a delivery and is the recovery path for a
receiver outage, an abandoned delivery or an out-of-order arrival.

## Delivery retries and replay

Return a `2xx` only after durable ingestion. Vault treats receiver `408`,
`425`, `429`, and `5xx` responses, plus transport failures, as retryable. It
uses exponential backoff starting at 30 seconds and capped at one hour. A
receiver may supply a delay-seconds `Retry-After`; Vault uses the longer delay
and bounds that receiver delay to 24 hours. Each delivery run has at most eight
attempts. An explicit replay starts another bounded run.

Any other non-`2xx` response, unsafe receiver URL, or missing delivery setup
is terminal for that delivery. Inspect customer-safe delivery state with `GET
/v1/organizations/{orgId}/partner-events/{eventId}/deliveries` or MCP
`partner_events_deliveries_list`. The HTTP result lists `data.items` with each
delivery's `deliveryId`, `eventId`, `subscriptionId`, status, attempt count,
timing, last failure and last HTTP status. It does not disclose receiver
secrets or response bodies.

To retry a terminal delivery after fixing the receiver, call `POST
/v1/organizations/{orgId}/partner-events/deliveries/{deliveryId}/replay` or
MCP `partner_events_deliveries_replay`. Replay reuses the same business event,
including its `id` and `occurredAt`; it does not create a replacement order,
deposit decision, or event ID. Keep the receiver idempotent and use polling if
replay cannot be scheduled.

The generated API reference and MCP catalog become the final authority when
signed delivery is enabled for the organization.
