Webhook Endpoints
Configure destinations and event subscriptions for signed Paybytoken events.
A Webhook Endpoint tells Paybytoken where to deliver signed events for one merchant account. Test and live mode have separate endpoints and signing secrets. The current merchant API permits one endpoint per account and mode; subscribe that endpoint to multiple exact events or resource wildcards.
Endpoints
| Method | Endpoint | Description |
|---|---|---|
GET | /api/v1/webhook_endpoints | List the account's endpoints. |
POST | /api/v1/webhook_endpoints | Create an endpoint and return its signing secret. |
GET | /api/v1/webhook_endpoints/:id | Retrieve endpoint configuration without its secret. |
PATCH | /api/v1/webhook_endpoints/:id | Update the destination URL, subscriptions or enabled status. |
POST | /api/v1/webhook_endpoints/:id/rotate | Rotate the signing secret with a limited overlap window. |
POST | /api/v1/webhook_endpoints/:id/test | Queue a signed test event for this endpoint. |
GET | /api/v1/webhook_endpoints/:id/metrics?hours=24 | Read delivery health for a 1–720 hour window. |
DELETE | /api/v1/webhook_endpoints/:id | Delete an endpoint. |
The Webhook Endpoint object
| Attribute | Type | Description |
|---|---|---|
id | string | Unique we_... identifier. |
account_id | string | Merchant account that owns the endpoint. |
url | string | HTTPS delivery destination in live mode. |
enabled_events | string[] | Exact event names, resource wildcards such as refund.*, or *. |
enabled | boolean | Whether Paybytoken can deliver to the endpoint. |
secret | string | Returned only when an endpoint is created. |
previous_secret_expires_at | timestamp or null | End of an active signing-secret overlap window. |
secret_rotated_at | timestamp or null | Most recent secret rotation time. |
created_at | timestamp | Creation time. |
updated_at | timestamp | Last update time. |
Store the creation secret immediately. Retrieval and update responses deliberately omit it. Use the rotate endpoint if the value is lost or exposed.
Rotation returns the replacement once and keeps the previous secret valid for a limited window.
During that window Paybytoken includes one v1 signature for each valid secret in the same
X-Webhook-Signature header. Deploy verification with both secrets, replace the stored current
secret, then remove the previous value after previous_secret_expires_at.
POST /:id/test emits webhook_endpoint.test only to the selected endpoint. It verifies routing,
signing and response handling but never represents a payment and must not trigger fulfillment.
Update status to enabled or disabled to control delivery without deleting configuration.
Deleting an endpoint removes its configuration; it does not remove the merchant events that were
already recorded.
See Fulfill orders with webhooks for raw-body verification, payloads and idempotent fulfillment.
Selectors use canonical dot notation. Use payment_intent.succeeded for one event,
payment_intent.* for a resource group, or * for all events. Colon-delimited selectors are
rejected.
Did this page answer your question?
Your feedback helps us improve the integration path.