Webhooks

Webhook delivery requires an approved subscription and an enabled event pipeline. A Partner RFQ key does not provision either automatically. Keep these implementations separate when selecting a verifier.

Availability

Surface	Authentication and current boundary
Durable Marketplace delivery	Organization-scoped subscriptions and deliveries through the Marketplace application/Firestore adapter and dispatch cron; rollout-controlled
/api/v1/webhooks management	Credential V2 x-api-key, webhooks audience and webhooks.manage scope; 60 requests/minute per key/organization/scope
Inbound /api/v1/webhooks/xjmf	Registered sender, X-XJMF-Signature, X-XJMF-Sender, X-XJMF-Timestamp; separate message contract

The management route accepts only analysis.complete, passport.created, and passport.verified. Its subscriptions are currently a process-local Map, not the durable Marketplace subscription store. Registration there does not subscribe an organization to quote/order events or establish cross-instance persistence.

Delivery basics

The durable Marketplace path uses HTTPS, signed requests, bounded retry, and terminal failure state. Timeout and non-2xx responses are failures. Consumers must tolerate duplicate delivery; bounded attempts do not guarantee eventual delivery during a prolonged outage.

Subscriptions and deliveries are organization-scoped. The durable delivery identity derives from source event ID and subscription ID. Exact enqueue replay validates the existing payload. Dispatch uses a lease token, so a stale worker cannot acknowledge a newer claim. Invalid rows are rejected. States are pending, leased, retrying, success, and failed. A failed persistence update is not reported as a successful acknowledgement.

The separate management-route delivery helper signs and sends process-local subscriptions, increments failure count, and disables after ten failures. It does not provide the durable retry/lease contract described above.

Event families

Current Marketplace domain-to-webhook mappings are:

• rfq.created, rfq.updated, rfq.expired
• quote.received, quote.accepted
• order.created, order.confirmed, order.completed
• payment.funded

Declared vocabulary or schema entries alone do not prove a producer is active. In particular, do not assume quote.updated, order.shipped, generic workflow events, or every planned delivery topic is emitted. A mapped payment event does not prove live payment-provider automation.

Example payload shape

{
  "event": "quote.received",
  "eventId": "evt_example",
  "timestamp": "2026-10-21T10:00:00.000Z",
  "apiVersion": "v1",
  "data": { "rfqId": "rfq_example", "quoteId": "quote_example" }
}

This illustrates the envelope, not a complete quote-event schema. The HTTP webhook-id is the delivery identity; retain eventId separately for source-event correlation.

Signature verification

For durable Marketplace delivery, use a Standard Webhooks-compatible verifier against the exact raw body and these headers:

• webhook-id
• webhook-timestamp (Unix seconds)
• webhook-signature (v1,<base64 HMAC-SHA256>)

The signed bytes are id.timestamp.rawBody. A whsec_ secret decodes its suffix from base64; other configured secrets use UTF-8 bytes. Verify timestamp freshness, compare decoded signatures in constant time, and reject missing/invalid fields before parsing or applying effects. Use the delivery ID to deduplicate verified requests. The same dispatcher also sends a legacy X-NowToPrint-Signature formatted t=<seconds>,v1=sha256=<hex> over timestamp.rawBody; it is not a raw-body-only signature.

The /api/v1/webhooks helper instead sends X-NowToPrint-Signature: sha256=<hex> over raw body only. Inbound XJMF expects bare hex HMAC-SHA256 of raw body; its separate timestamp header is checked within five minutes. Do not reuse one verifier across these contracts. XJMF's process-local replay cache is not durable exactly-once protection.

The Marketplace dispatcher rejects redirects and checks HTTPS/host patterns. These checks are not a universal DNS/network-isolation guarantee. Keep webhook secrets out of logs.

Consumer guidance

• Verify first, then persist acceptance and return 2xx; enqueue heavy work separately.
• Deduplicate delivery IDs and reconcile source state when a terminal failure or ambiguous outcome occurs.
• Log event/delivery correlation without secrets or private evidence.
• Coordinate secret rotation and enabled event families with the integration owner.

Related docs