Webhook Event Reference

Each terminal exposes a single webhook URL. Set or update it with:

PUT /Terminals/{id}/webhook

{
  "url": "https://example.com/bead/webhooks",
  "signingSecret": "b5b9ee11f2b447c9b3294ff9a8f6f53c"
}

• url – your HTTPS endpoint

• signingSecret – a 32-byte hex string you must store; every webhook call is HMAC-signed with this secret.

Current payload (raw payment object)

The POST body is the entire payment record (see sample below). There is no envelope yet (eventId, eventType, etc.).

Signature header

X-Bead-Signature: sha256=9d6309b739a8e5b87e3c2b8d1d4fbc17e5e3c7f3c5b5a9d3e…

Algorithm HMAC-SHA256(signingSecret, rawRequestBody) Verify before you queue or process the payload.

Sample body (truncated)

{
  "id": "pay_123",
  "terminalId": "term_abc",
  "trackingId": "trk_456",
  "statusCode": "processing",
  "amounts": { /* … */ },
  "transactions": [ /* … */ ],
  /* full schema shown in API spec */
}

statusCode values

Code	Meaning
created	Payment record created; awaiting funds
processing	Funds detected; conversion / settlement underway
completed	Funds received and credited
underpaid	Customer sent less than requested
overpaid	Customer sent more than requested
expired	No funds before window elapsed
invalid	Unsupported asset, compliance block, or similar
cancelled	Cancelled by customer or merchant
fullyRefunded (reserved)	Entire payment refunded
partiallyRefunded (reserved)	Partial refund completed

Delivery mechanics

• Method POST application/json

• Timeout 10 s per attempt

• Retries Up to 5 (2 s, 4 s, 8 s, 16 s, 32 s) until any 2xx

• Source IPs Publish soon—allow by X-Forwarded-For header meanwhile

Best-practice checklist

✔︎ Best-practice action	Why it matters
Verify X-Bead-Signature with the signingSecret before processing	Blocks spoofed or tampered requests
Respond within 200 ms with any 2xx (202 Accepted recommended)	Prevents automatic retries and duplicate events
Queue the payload, then perform long-running work asynchronously	Keeps webhook thread fast and resilient
Dedupe on trackingId + statusCode (or eventId when introduced)	Network retries can deliver the same update multiple times
Use separate webhook URLs for sandbox and production	Avoids mixing test data with live transactions
Rotate the signingSecret periodically via PUT /Terminals/{id}/webhook	Limits blast radius if a secret leaks

Roadmap (for planning)

Later releases will add:

• Envelope (eventId, eventType, created, data) wrapping the same body

• Additional event types such as terminal.status.changed and payment.refund.completed

Your current HMAC logic will continue to work—the signature will be computed over the new JSON body—so build your handler today and extend it when the new format ships.