Webhook Management

Webhook notifications are sent to your system when payment status updates occur. Webhooks are configured per terminal, allowing you to direct updates to the appropriate service endpoint.

Set Webhook URL

Endpoint

PUT /Terminals/{terminalId}/webhook

Authorization: Bearer token

Path Parameter

Name	Type	Required	Description
terminalId	string	✅ Yes	The terminal for webhook config

Request Body

Field	Type	Required	Description
url	string	✅ Yes	Full HTTPS URL to receive notifications

Example Request

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

Success Response

HTTP 200 OK

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

The signingSecret is used to verify the authenticity of incoming webhook events.

Delete Webhook URL

Endpoint

DELETE /Terminals/{terminalId}/webhook

Authorization: Bearer token

Path Parameter

Name	Type	Required	Description
terminalId	string	✅ Yes	The terminal to clear the webhook for

Example Request

curl -X DELETE "https://api.test.devs.beadpay.io/Terminals/{{terminalId}}/webhook" \
  -H "Authorization: Bearer {{ACCESS_TOKEN}}"

Success Response

HTTP 200 OK

Webhook URL is cleared.

Tips

• Ensure your webhook endpoint can handle POST requests and respond with 200 OK promptly.

• Webhook payloads include status codes like completed, underpaid, overpaid, etc.

• Use a unique URL per environment (e.g., dev, staging, prod) to test safely.