Register a webhook endpoint
POST/v1/webhook_endpoints
Returns the signing secret **once**, like an API key. Verify every delivery against it: the signature covers the timestamp and the body, and signatures older than five minutes must be rejected.
The URL must be public HTTPS. Private, loopback and link-local destinations are refused, and the check is repeated at delivery time in case DNS is repointed afterwards.
A URL has one endpoint. Registering one that already exists sets its events and answers 200 with the same id and secret.
Body
| Field | Type | Description |
|---|---|---|
| urlrequired | string | |
| events | array of string | The event types to send; empty means every one. Email
sends email.sent, email.delivered,
email.undelivered (a bounce), email.failed,
email.complained, email.canceled, email.opened,
email.clicked and email.received. |
Example
curl -X POST https://api.woyra.io/v1/webhook_endpoints \
-H "Authorization: Bearer $WOYRA_KEY" \
-H 'Content-Type: application/json' \
-d '{
"url": "https://api.yourapp.com/hooks/woyra"
}'Response
200 The URL was already registered; its event filter is updated.
| Field | Type | Description |
|---|---|---|
| object | "webhook_endpoint" | |
| id | string | |
| url | string | |
| events | array of string | |
| status | string | A consistently failing endpoint is quarantined rather than hammered. One of active, quarantined, disabled. |
| consecutive_failures | integer | |
| created_at | timestamp | |
| secret | string | Present only in the response to creation. |
Errors
| Status | Codes |
|---|---|
| 400 | invalid_request, unsupported_version |
Also in Webhooks
- GET /v1/webhook_endpoints — List webhook endpoints
- DELETE /v1/webhook_endpoints/{id} — Remove a webhook endpoint
- GET /v1/webhook_deliveries — List webhook deliveries
- GET /v1/webhook_deliveries/{id} — Inspect one delivery
- POST /v1/webhook_deliveries/{id}/replay — Send a delivery again
- POST /v1/webhook_endpoints/{id}/release — Take an endpoint out of quarantine