Webhooks
We call you when something happens, signed so you can trust it.
Register an endpoint with POST /webhooks and we POST a JSON event to it when
something happens. The URL must be https:// — the payload can carry the text
of your customers' messages, and plain http would send that in the clear.
The response that creates an endpoint is the only one that carries the
signing secret in full. Every later read answers with secret_preview instead.
Events
| Event | Raised for |
|---|---|
message.sent | Campaign messages only |
message.delivered | Any message |
message.opened | Campaign messages only |
message.clicked | Campaign messages only |
message.replied | Campaign messages only |
message.bounced | Campaign messages only |
message.failed | Any message |
message.received | Any message |
campaign.completed | Any message |
contact.created | Any message |
contact.updated | Any message |
The five marked `campaign_only` are only ever raised for messages born from a campaign. The tables behind single sends do not record those states at all, so subscribing to them and sending one-off messages means waiting for events that will never arrive.
Verifying the signature
Each request carries X-SendKuy-Signature, formatted t={timestamp},v1={hmac}.
`hash_hmac('sha256', timestamp . '.' . rawRequestBody, secret)`. Compute it over the raw body, before any JSON parsing — re-encoding changes the bytes and the signature will not match. Compare with a constant-time comparison, and reject timestamps that are too old to stop replays.
Headers
| Header | Meaning |
|---|---|
X-SendKuy-Event | The event name, the same value as `events` on the endpoint. |
X-SendKuy-Event-Id | The id of this delivery attempt's event. It stays the same across all six attempts, so use it to make your handler idempotent — a retry is the same event, not a second one. |
Retries
6 attempts: the first immediately, then after 1m, 5m, 30m, 2h, 12h.
The first call is immediate; the five entries above are the waits before each following attempt. Answer 2xx quickly — the call times out after 10 seconds, and a slow handler is a failed delivery. Repeated failures eventually disable the endpoint, which shows up as `disabled_at`.