Webhook Management

Webhook notifications let your backend react in real time when a payment’s statusCode changes. Each terminal has exactly one default webhook URL. You can:

• Set or update the URL

• Delete the URL

• Verify events with the returned signingSecret

Per-payment overrides Passing a webhookUrls array in POST /payments/crypto adds extra endpoints for that single payment. The terminal webhook configured here still receives every event.

Set / Update the webhook URL

Endpoint

PUT /Terminals/{terminalId}/webhook

Headers

Authorization: Bearer {access_token} Content-Type: application/json

Request body

{
  "webhookUrl": "https://yourapp.com/webhooks/payment-status"
}

Example (cURL)

curl -X PUT "https://api.test.devs.beadpay.io/Terminals/TERM-123/webhook" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"webhookUrl":"https://yourapp.com/webhooks/payment-status"}'

Success response

{
  "terminalId":   "TERM-123",
  "webhookUrl":   "https://yourapp.com/webhooks/payment-status",
  "signingSecret": "abc123secret",
  "updated":      "2025-07-09T15:02:10Z"
}

Keep signingSecret safe—use it to verify the x-webhook-signature header on incoming events.

Delete the webhook URL

Endpoint

DELETE /Terminals/{terminalId}/webhook

Example (cURL)

curl -X DELETE "https://api.test.devs.beadpay.io/Terminals/TERM-123/webhook" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Success response

{
  "terminalId": "TERM-123",
  "webhookUrl": null
}

Best-practice tips

Tip	Why
Respond with HTTP 200 quickly	Any non-2xx triggers retries (exponential back-off for 24 h).
Verify every event (x-webhook-signature + signingSecret)	Prevent spoofing and replays.
Use environment-specific URLs (dev / staging / prod)	Keeps test traffic isolated.
Handle enum statusCode strings (completed, underpaid, etc.)	Numeric codes were removed in May 2025.
Remember fan-out	Events go to this URL and any webhookUrls supplied per payment.

Need help? Email [email protected].