Webhooks

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):

  1. URL: the address that will receive the events, in https://, 2,048 characters at most. 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, a password or a fragment (#…).
  2. Description (optional, 120 characters at most): what this webhook is for.
  3. Events: the webhook events to receive; all thirteen 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. The button works at most ten times a minute per store (429 rate_limited beyond), and not on a disabled webhook (409 webhook_disabled):

ping
{
  "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:

FieldContent
idThe id of the webhook event (UUID), the same at every attempt.
typeThe event type, for instance order.paid.
createdAtWhen the event happened, ISO 8601 in UTC.
storeThe store: id and slug.
dataThe object concerned, exactly as the public API returns it (the order of GET /v1/orders/{id}…).

And these headers:

HeaderContent
Content-Typeapplication/json
User-AgentKivoo-Webhooks/1.0
Kivoo-Signaturet=<timestamp>,v1=<signature>: see Verify the signature.
Kivoo-Event-IdThe id of the event, stable from one attempt to the next: your idempotency key.
Kivoo-Event-TypeThe type of the event.
Kivoo-Delivery-AttemptThe 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 a 2xx answer is not read; the body of any other answer is kept in the log, truncated (see Retries and journal).
  • Do the long work (sending an email, calling another service) after answering, in a job queue for instance.
  • Kivoo does not follow redirects: a 3xx answer is a failure. Give the final address.
  • A failure is retried several times, over almost a day: see Retries and journal.

When Kivoo sends nothing

  • A suspended store, or one closed because its owner deleted their account, sends no event any more: its pending deliveries stop with the error store_unavailable, and no webhook can be added to it. Its API keys are refused too (403 store_unavailable).
  • A disabled webhook, by you or automatically, receives nothing, and does not receive later what happened in the meantime.
  • An event type the webhook is not subscribed to is not sent. A type Kivoo adds after the webhook was created is not checked for it: open the webhook’s page to add it.

On this page