Webhooks
Receive the events of your store on your server, as they happen, signed by Kivoo.
A webhook is an HTTPS address of your server to which Kivoo sends, with a POST request, the webhook events of your store: a paid order, a new customer, a published product. No more polling the API: your server knows as soon as it happens.
Webhooks are independent of API keys: a webhook needs no key, and a revoked key cuts no webhook.
Add a webhook
In the dashboard, open your store, then Paramètres › Développeur › Webhooks (Settings › Developer › Webhooks) and click Ajouter un webhook (Add a webhook):
- URL: the address that will receive the events, in
https://. A private or local address (localhost,127.0.0.1,10.x.x.x,192.168.x.x…) is refused, like a URL carrying a user name or a password. - Description (optional): what this webhook is for.
- Events: the webhook events to receive; all six are checked by default.
A store has at most five webhooks. The owner and Admin members manage them: edit, disable, enable, delete.
The signing secret
When the webhook is created, Kivoo shows its signing secret, which starts with whsec_. Like an API key, it is shown only once: keep it on your server. It lets you check that each request really comes from Kivoo, see Verify the signature.
Régénérer le secret (regenerate the secret), in the webhook’s page, shows a new one; the old one stops signing at once.
Send a test
The Envoyer un test (send a test) button of the webhook’s page sends a ping event, signed like the others, to check that your server answers:
{
"id": "0a9b8c7d-6e5f-4a3b-9c2d-1e0f9a8b7c6d",
"type": "ping",
"createdAt": "2026-09-26T10:00:00.000Z",
"store": { "id": "6f1c2d3e-4b5a-4c6d-8e9f-0a1b2c3d4e5f", "slug": "atelier-nour" },
"data": { "message": "Kivoo webhook test", "sentAt": "2026-09-26T10:00:00.000Z" }
}What Kivoo sends
Each delivery is a POST request whose JSON body is the envelope of the event:
| Field | Content |
|---|---|
id | The id of the webhook event (UUID), the same at every attempt. |
type | The event type, for instance order.paid. |
createdAt | When the event happened, ISO 8601 in UTC. |
store | The store: id and slug. |
data | The object concerned, exactly as the public API returns it (the order of GET /v1/orders/{id}…). |
And these headers:
| Header | Content |
|---|---|
Content-Type | application/json |
User-Agent | Kivoo-Webhooks/1.0 |
Kivoo-Signature | t=<timestamp>,v1=<signature>: see Verify the signature. |
Kivoo-Event-Id | The id of the event, stable from one attempt to the next: your idempotency key. |
Kivoo-Event-Type | The type of the event. |
Kivoo-Delivery-Attempt | The attempt number, from 1 to 8. |
Answer Kivoo
- Answer with a 2xx status within 10 seconds: that is what counts as a successful delivery. The body of your answer is not read.
- Do the long work (sending an email, calling another service) after answering, in a job queue for instance.
- Kivoo does not follow redirects: a
3xxanswer is a failure. Give the final address. - A failure is retried several times, over almost a day: see Retries and journal.