Webhooks API

All endpoints require Bearer JWT.

---

GET /v1/webhooks

List all registered webhook endpoints.

Response 200

[
  {
    "id": "wh_01j...",
    "url": "https://yourapp.com/webhooks/notifo",
    "events": ["message.delivered", "message.failed"],
    "isActive": true,
    "lastTriggeredAt": "ISO8601 | null",
    "failureCount": 0,
    "createdAt": "ISO8601"
  }
]

---

POST /v1/webhooks

Register a new webhook endpoint.

Request

{
  "url": "https://yourapp.com/webhooks/notifo",
  "events": ["message.delivered", "message.failed"]
}

Field	Type	Required	Description
url	string	yes	HTTPS endpoint
events	string[]	no	Defaults to all 5 events

Valid events: message.queued, message.sent, message.delivered, message.read, message.failed

Response 201

{
  "id": "wh_01j...",
  "url": "https://yourapp.com/webhooks/notifo",
  "events": ["message.delivered", "message.failed"],
  "isActive": true,
  "secret": "a1b2c3...",
  "warning": "Store this signing secret — it will not be shown again. Verify HMAC-SHA256 signature on every incoming request."
}

caution

The secret is shown once. See Signature Verification →

---

DELETE /v1/webhooks/:id

Delete a webhook endpoint.

Response: 204 No Content

---

PATCH /v1/webhooks/:id/enable

Enable a previously disabled webhook.

Response 200 — updated webhook object.

---

PATCH /v1/webhooks/:id/disable

Disable a webhook without deleting it.

Response 200 — updated webhook object.