API reference
Webhooks API
Register endpoints, rotate secrets, read the delivery log, redeliver and test.
Base URL https://api.overads.io/public/v1. Every route needs a key with the scope shown, sent as Authorization: Bearer sk_live_YOUR_KEY. The machine-readable contract is at https://api.overads.io/public/v1/openapi.json, no key needed. Scope for this family: webhooks:manage.
This page is the management surface. The events, the envelope, the signature and the retry policy are on the Webhooks page. Endpoints can also be managed in the app under Settings > Webhooks.
GET/webhooks
Scope webhooks:manage. List endpoints. Secrets are never included.
Response: { data: Endpoint[] } with id, name, url, events, active, consecutiveFailures, lastDeliveryAt, createdAt, updatedAt.
curl https://api.overads.io/public/v1/webhooks -H "Authorization: Bearer sk_live_YOUR_KEY"POST/webhooks
Scope webhooks:manage. Register an endpoint. The signing secret is returned once, here.
| Body | Type | Meaning | |
|---|---|---|---|
name | string | required | 1 to 80 characters. |
url | string | required | https only. Localhost, private and link-local addresses, and URLs carrying credentials, are refused with WEBHOOK_URL_REFUSED. |
events | string[] | required | One or more event names from the catalogue. Duplicates and unknown names are refused. |
Response: 201 with { data: Endpoint & { secret }, warnings: [] }. Store secret (whsec_ plus 64 hex characters); it is not shown again.
{
"data": {
"id": "e1d2…",
"name": "Zapier catch hook",
"url": "https://hooks.example.com/overads",
"events": ["post.published", "post.failed"],
"active": true,
"consecutiveFailures": 0,
"lastDeliveryAt": null,
"createdAt": "…",
"updatedAt": "…",
"secret": "whsec_0f9a…"
},
"warnings": []
}curl -X POST https://api.overads.io/public/v1/webhooks -H "Authorization: Bearer sk_live_YOUR_KEY" -H "Content-Type: application/json" \
-d '{ "name": "Zapier catch hook", "url": "https://hooks.example.com/overads", "events": ["post.published", "post.failed"] }'GET/webhooks/:id
Scope webhooks:manage. One endpoint.
Response: { data: Endpoint }.
curl https://api.overads.io/public/v1/webhooks/e1d2c3b4-a5f6-4e7d-8c9b-0a1b2c3d4e5f -H "Authorization: Bearer sk_live_YOUR_KEY"PATCH/webhooks/:id
Scope webhooks:manage. Rename, re-point, re-subscribe, pause or resume.
| Body | Type | Meaning | |
|---|---|---|---|
name | string | optional | 1 to 80 characters. |
url | string | optional | https only; re-checked against the same address rules. |
events | string[] | optional | Replaces the subscription list. |
active | boolean | optional | false pauses the endpoint. true resumes it and resets consecutiveFailures to 0. |
Response: { data: Endpoint, warnings: [] }.
curl -X PATCH https://api.overads.io/public/v1/webhooks/e1d2c3b4-a5f6-4e7d-8c9b-0a1b2c3d4e5f -H "Authorization: Bearer sk_live_YOUR_KEY" -H "Content-Type: application/json" \
-d '{ "active": true }'DELETE/webhooks/:id
Scope webhooks:manage. Delete an endpoint and its delivery log.
Response: 204, no body.
curl -X DELETE https://api.overads.io/public/v1/webhooks/e1d2c3b4-a5f6-4e7d-8c9b-0a1b2c3d4e5f -H "Authorization: Bearer sk_live_YOUR_KEY"POST/webhooks/:id/rotate-secret
Scope webhooks:manage. Mint a new signing secret. The old one stops verifying with the next send.
Response: { data: Endpoint & { secret }, warnings: [] }.
curl -X POST https://api.overads.io/public/v1/webhooks/e1d2c3b4-a5f6-4e7d-8c9b-0a1b2c3d4e5f/rotate-secret -H "Authorization: Bearer sk_live_YOUR_KEY"GET/webhooks/:id/deliveries
Scope webhooks:manage. The last deliveries, newest first.
| Query | Type | Meaning | |
|---|---|---|---|
limit | integer | optional | 1 to 50, default 50. |
Response: { data: Delivery[] } with id, event, attempt (0 until the first try), statusCode (null when no response arrived), error, nextAttemptAt, deliveredAt, createdAt and the payload that was sent.
curl "https://api.overads.io/public/v1/webhooks/e1d2c3b4-a5f6-4e7d-8c9b-0a1b2c3d4e5f/deliveries?limit=20" -H "Authorization: Bearer sk_live_YOUR_KEY"POST/webhooks/:id/deliveries/:deliveryId/redeliver
Scope webhooks:manage. Send a past delivery again, as a new delivery with the old payload.
Response: 201 with { data: Delivery, warnings: [] }.
curl -X POST https://api.overads.io/public/v1/webhooks/e1d2c3b4-a5f6-4e7d-8c9b-0a1b2c3d4e5f/deliveries/5a6b7c8d-9e0f-4a1b-8c2d-3e4f5a6b7c8d/redeliver -H "Authorization: Bearer sk_live_YOUR_KEY"POST/webhooks/:id/test
Scope webhooks:manage. Queue a signed ping so you can verify the signature end to end.
ping cannot be subscribed to; it only ever comes from this route. Its data is { endpointId, message }.
Response: 201 with { data: Delivery, warnings: [] }.
curl -X POST https://api.overads.io/public/v1/webhooks/e1d2c3b4-a5f6-4e7d-8c9b-0a1b2c3d4e5f/test -H "Authorization: Bearer sk_live_YOUR_KEY"