Webhook Management

Webhook notifications let your backend react in real time when a payment statusCode changes. Each terminal has exactly one default webhook URL. You can set or update the URL, delete the URL, and verify events using the returned signingSecret.

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

Set or update the webhook URL

Endpoint

PUT /Terminals/{terminalId}/webhook

Purpose

Set or change the default payment status webhook URL for a single terminal.

Request headers

Header	Value
Authorization	Bearer <access_token>
Content-Type	application/json
Accept	application/json

Request body

Field	Type	Required	Notes
url	string	Yes	Fully qualified https URL where you want to receive events.

Example request (cURL)

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

Success responses

200 OK

{
  "url": "https://yourapp.com/webhooks/payment-status",
  "signingSecret": "abc123secret"
}

Additional success statuses

• 202 Accepted

• 204 No Content

These additional statuses indicate the request was accepted; the response body may be empty.

Validation or auth errors return standard ProblemDetails (for example 400 Bad Request, 401 Unauthorized, 403 Forbidden).

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

Delete the webhook URL

Endpoint

DELETE /Terminals/{terminalId}/webhook

Purpose

Remove the default webhook URL for a terminal. Events for that terminal will no longer be sent to a terminal level URL, though any per payment webhookUrls will still be used.

Request headers

Header	Value
Authorization	Bearer <access_token>
Content-Type	application/json
Accept	application/json

Example request (cURL)

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

Success status

• 204 No Content (empty response body)

If the request is invalid, the API returns a standard validation error payload (for example 400 Bad Request with a ProblemDetails body).

Best practice tips

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