Skip to content
Stashtab Docs
Esc
↑↓navigate↵open⌘Jpreview
On this page

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.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:

{
  "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.

Was this page helpful?