Webhook Event Reference

Webhook Event Reference

Webhook notifications let your backend react to changes without polling. This page is the shared operational reference for Bead webhook delivery.

Use this page for:

• delivery behavior and retries

• signature verification

• idempotent processing

• ordering and replay safety

• production operating guidance

Use the product-specific webhook page for:

• setup and registration steps

• payload fields and examples

• event types or status meanings

• product-specific business handling

What this page does and does not define

This page defines the shared operational model for webhook handling.

This page does not define a single canonical payload schema for every webhook family. Payload shape is product-specific. Do not assume a shared cross-product envelope unless the relevant product page explicitly documents one.

Where events go

Payments

Bead supports two payment webhook delivery paths:

• Terminal default webhook Configured at the terminal level. Applies to all payments created by that terminal.

• Per-payment webhook URLs Supplied through webhookUrls on POST /Payments/crypto. Applies only to that individual payment.

When both are present, Bead fans out the same payment event to the terminal webhook and to each URL listed in webhookUrls.

Other webhook families

Other product areas may define their own webhook registration path and event selection model. Use the product-specific webhook page for setup details.

Configure the terminal default webhook

Payment webhooks are typically configured at the terminal level using OAuth-authenticated terminal endpoints:

• PUT /Terminals/{id}/webhook

• GET /Terminals/{id}/webhook

• DELETE /Terminals/{id}/webhook

Minimal example:

PUT /Terminals/{id}/webhook
Authorization: Bearer {access_token}
Content-Type: application/json
Accept: application/json

{
  "webhookUrl": "https://example.com/bead/webhooks"
}

Notes:

• Use an HTTPS endpoint.

• Terminal management endpoints use OAuth, not the Payments API key.

• If you do not manage terminal configuration directly, coordinate with Bead support using the terminalId and desired webhook URL.

Signature header

Webhook requests include the x-webhook-signature header.

Example:

x-webhook-signature: t=1752067200,s=9d6309b739a8e5b87e3c2b8d1d4fbc17e5e3c7f3c5b5a9d3e...

Where:

• t is a Unix epoch timestamp in seconds

• s is the HMAC-SHA256 signature of the raw request body using the webhook signing secret

Always verify the signature against the raw request body before parsing or processing JSON.

Signature verification flow

1. Read the raw request body exactly as received.

2. Read the x-webhook-signature header.

3. Parse the t and s values.

4. Recompute the HMAC-SHA256 signature using your signing secret and the raw body.

5. Compare your computed signature to the received signature using a constant-time comparison.

6. Optionally reject stale timestamps outside your allowed freshness window.

7. Only then parse and process the JSON body.

Delivery mechanics

• Method: HTTP POST

• Content type: application/json

• Success condition: a successful 2xx response, preferably 200 OK

• Timeout: 10 seconds per attempt

• Retry behavior: exponential backoff for up to about 24 hours if a successful 2xx response is not returned

• Delivery model: at least once

• Ordering: do not assume perfect ordering

• One event per change: webhook families such as Payments send one event per status change

If your endpoint does not return a successful 2xx response quickly, Bead may retry the same event.

Recommended processing model

1. Accept the request.

2. Preserve the raw body and headers.

3. Verify the signature.

4. Parse the JSON payload.

5. Build an idempotency key from the identifiers provided by the payload.

6. Persist or enqueue the event.

7. Apply business logic asynchronously if needed.

8. Return a 2xx response quickly.

Idempotency and duplicate handling

Treat webhook delivery as at least once.

If a webhook family does not provide a dedicated eventId, derive idempotency from the identifiers in the payload.

For payment webhooks, a practical idempotency key is:

• trackingId

• statusCode

• receivedTime when present

Do not treat duplicate deliveries as errors. They are a normal part of retry-safe webhook delivery.

Ordering and state convergence

Do not assume events arrive in perfect order.

Your handler should:

• compare the incoming event to your current known state

• ignore older or duplicate state transitions when appropriate

• converge on the latest valid state

If you need to confirm the latest current state, call the relevant read endpoint for that product area.

Security checklist

• Use HTTPS webhook endpoints.

• Verify x-webhook-signature on every request.

• Treat the signing secret like a password.

• Reject malformed or unsigned requests.

• Consider rejecting stale timestamps to reduce replay risk.

• Avoid logging secrets or full sensitive headers.

• Keep development, staging, and production webhook URLs separate.

• Do not rely on source IP allow listing alone. Signature verification should be your primary trust control.

Operational checklist

• Return a 2xx response quickly.

• Queue or persist work before heavy downstream processing.

• Instrument request logging and delivery failures.

• Track retry volume and error rates.

• Build idempotent consumers.

• Test both happy-path and non-happy-path events in sandbox.

Product-specific pages

Use the product-area webhook page for payload fields, examples, and business handling:

• Payment Webhooks

• Webhooks for Application Events

Forward compatibility

New webhook families may add dedicated event types, wrapper envelopes, or event IDs.

Always validate against the product-specific documentation for that webhook family rather than assuming the same body shape across all products.