Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Webhook Management

Configure or remove the default webhook URL for a terminal. Each terminal can have one default webhook URL for payment status events. You can also provide payment-specific webhook URLs when creating a payment.

Set or update the webhook URL

Use this operation to create or replace the default payment status webhook URL for a terminal.

Endpoint

PUT https://api.test.devs.beadpay.io/Terminals/{id}/webhook

Authentication

Use your admin API key in the request header for terminal management operations. This endpoint does not accept a terminal payments API key. Using a terminal payments API key will return 403 Forbidden.

Request headers

Header
Value

X-Api-Key

{adminApiKey}

Content-Type

application/json

Accept

application/json

Path parameter

Name
Type
Description

id

string

Terminal identifier returned by Create Terminal, List Terminals, or Get Terminal.

Request body

Field
Type
Required
Description

url

string (URI)

Yes

Fully qualified HTTPS URL where terminal-level payment status events should be delivered. Maximum 512 characters.

Example request

curl --request PUT "https://api.test.devs.beadpay.io/Terminals/67f10123456789abcdef0456/webhook" \
--header "X-Api-Key: {adminApiKey}" \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
--data '{
"url": "https://yourapp.com/webhooks/payment-status"
}'

Example response

Store signingSecret securely. Use it to verify the x-webhook-signature header on all incoming terminal webhook deliveries. Treat it like a password and do not log it or expose it in client-side code.

Success responses

Code
Meaning

200

Webhook URL set or updated successfully.

202

Request accepted for processing.

204

Request completed with no response body.

Error responses

Code
Meaning

400

The request body is invalid, such as a missing or malformed URL.

401

The admin API key is missing or invalid.

403

The caller is authenticated but not permitted to manage the specified terminal, or a terminal payments API key was used instead of an admin API key.

404

No terminal was found for the supplied id.

409

A conflicting terminal state prevented the update.

Delete the webhook URL

Use this operation to remove the default webhook URL from a terminal. After removal, terminal-level payment status events are no longer delivered to a default webhook URL.

Endpoint

DELETE https://api.test.devs.beadpay.io/Terminals/{id}/webhook

Authentication

Use your admin API key in the request header for terminal management operations.

Request headers

Header
Value

X-Api-Key

{adminApiKey}

Accept

application/json

Path parameter

Name
Type
Description

id

string

Terminal identifier returned by Create Terminal, List Terminals, or Get Terminal.

Example request

Success response

204 No Content — no response body is returned on success.

Error responses

Code
Meaning

400

The request is invalid.

401

The admin API key is missing or invalid.

403

The caller is authenticated but not permitted to manage the specified terminal.

404

No terminal was found for the supplied id.

Signature verification

When you set or update a terminal webhook, the response includes a signingSecret. Store it securely — you will use it to verify the x-webhook-signature header on every incoming terminal webhook delivery.

The signature header format is:

Where t is a Unix epoch timestamp in milliseconds and s is a Base64-encoded HMAC-SHA256 digest of the signed message t + "." + rawBody, computed using the base64-decoded bytes of signingSecret as the HMAC key.

For full verification steps and a Node.js code example, see How do I verify that a webhook really came from Bead?.

Delivery behavior

The terminal webhook is the default event destination for all payments on that terminal. You can also supply payment-specific webhookUrls when creating a payment if a single payment needs additional event destinations.

x-webhook-signature is included on both terminal-level webhook deliveries and per-payment deliveries sent to webhookUrls — both use the same terminal's signingSecret and the same signing logic. Each individual delivery carries its own t (timestamp) generated at send time, so the resulting s (signature) value is different per delivery even when the JSON body is identical across recipients. Your verification code doesn't need to change based on which delivery path an event arrived on.

Important — signing depends on the terminal having a secret configured. A terminal only has a signingSecret once you've called PUT /Terminals/{id}/webhook on it at least once. If you only ever use webhookUrls and have never set a terminal-level default webhook, that terminal has no signingSecret, and its webhookUrls deliveries are sent without an x-webhook-signature header — silently, with no error or warning. If you plan to rely primarily on webhookUrls for routing, set a terminal-level default webhook first (even one you don't actively use) specifically to establish the signingSecret, then verify all deliveries — terminal-level and per-payment — using that secret.

Best practices

  • Return a 2xx response quickly from your webhook consumer.

  • Make webhook processing idempotent so retries do not create duplicate work.

  • Use environment-specific webhook URLs for Sandbox and Production.

  • Treat the signing secret like any other credential and do not log it or expose it in client-side code.

  • Set a terminal-level webhook (to establish a signingSecret) even if webhookUrls is your primary delivery mechanism — otherwise your deliveries may be unsigned with no indication anything is missing.

Notes

  • The request body field is url, not webhookUrl.

  • Use your admin API key for terminal webhook management.

  • Use the terminal payments API key for payment operations only, not for terminal configuration changes.

Related operations

PreviousDelete Terminal
NextManaging Tender Types

Last updated