Webhook Endpoints
Register and manage the URLs Wajub sends signed event notifications to.
A webhook endpoint is a URL you register to receive signed, real-time notifications for the event types you subscribe to. See Webhooks for the full setup guide.
private key required
Managing webhook endpoints requires the private key (sk.). A live endpoint's URL must use
https://, otherwise the call answers 422; a sandbox endpoint also accepts http://.
Endpoints
The path is /webhooks
This resource is exposed under /webhooks, not /webhook-endpoints, webhook-endpoints here
refers to the product concept (the registered URL and its configuration), not the events it
receives (see Event catalog).
| Method | Path | Description |
|---|---|---|
POST | /webhooks | Create a webhook endpoint |
GET | /webhooks | List webhook endpoints |
GET | /webhooks/{id} | Retrieve a webhook endpoint |
PUT | /webhooks/{id} | Update a webhook endpoint |
DELETE | /webhooks/{id} | Delete a webhook endpoint |
POST | /webhooks/{id}/rotate-secret | Rotate the signing secret |
Rules an endpoint must follow
Each rule refused is a 422 naming the field.
| Rule | Refused with |
|---|---|
A live endpoint's URL uses https://. A sandbox one may use http:// | A live webhook endpoint must use an https:// URL. |
The URL resolves to a public internet address: private and internal addresses are refused. For a local test, use wajub listen | The url must not point to a private or internal IP address., or must not resolve to a private IP address for a hostname |
| One endpoint per URL in each environment, at creation and when a URL is changed | A webhook endpoint with this URL already exists. |
At least one event type, at creation and on PUT. ["*"] takes every type; an empty list is refused | The events field must have at least 1 items. |
| A URL up to 2048 characters, a type up to 100, a description up to 500 | The field's own length message |
Event type names are not checked: a misspelt one is stored and never matches. Copy them from the Event catalog.
PUT /webhooks/{id} with "active": false disables the endpoint without deleting it: nothing more
is delivered to it, and the retries already queued for it are abandoned. "active": true enables it
again; events recorded in between are not sent, and you can replay them with
POST /events/{id}/resend.
Events
| Event | Trigger |
|---|---|
webhook_endpoint.created | Endpoint registered |
webhook_endpoint.updated | Endpoint updated |
webhook_endpoint.deleted | Endpoint removed |