Receive partner webhooks
Verify, persist, and reconcile signed partner event deliveries.
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 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.assesseddeposit.acceptedorder.shippedorder.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:
{
"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:
{
"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.