Customer · Settings

Adding a webhook

Set up a webhook subscription that automatically notifies your own system when the status of your orders changes (picked up, delivered, cancelled…), the signing secret and troubleshooting.

A webhook means Courino automatically sends a message to an address in your own system when something happens to your order (e.g. the courier picked up or delivered the parcel). That way your software doesn't have to keep asking for the status.

Your software developer usually gives you the address and the events needed. If you don't see this card, your account doesn't have the API and webhooks permission; ask your courier company for it.

Adding a subscription

Click My details in the left menu.
On the Webhook (event notification) card, click Add subscription.
Type the address your developer gave you in the URL (https://…) box. For security, use an address that starts with https://.
Leave KOS (signed JSON) selected as the Format. Legacy system (orderId) is only for those who want to keep an old integration unchanged.
If you like, write a note in the Description box (e.g. "Warehouse system").
In the Events section, tick the statuses you want to hear about (e.g. Picked up, Delivered, Cancelled).
Make sure Enabled is ticked and click Save.
The signing secret appears in a green box (it starts with whsec_). Take it with Copy and pass it to your developer securely.

The signing secret is shown only once. If you lose it, get a new one with Rotate secret next to the subscription; the old secret stops working at once.

The message that is sent

Each message is JSON and contains the order's number, status, times, your reference number, amount and the courier's name. Personal data such as the recipient's phone number is not sent.
Each message is signed with the X-KOS-Signature header. Your developer checks this signature with the secret to know the message really came from Courino.
If your address doesn't answer or returns an error, the message is retried several times at increasing intervals (about 1.5 hours in total). The X-KOS-Delivery value doesn't change when the same message is retried; your developer can skip the second one.
Delivery code, rating request and "your courier is on the way" messages go only to the recipient; they are not sent by webhook.

Your developer finds how to verify the signature in the API docs above the card. See Integration API for details.

Managing subscriptions

Edit: Changes the address, events or description. To pause messages for a while, untick Enabled.
Rotate secret: Creates a new signing secret. Use it if you think someone else has the secret, and pass the new secret to your developer.
Delete: Removes the subscription completely.
You can have at most 5 subscriptions.

Having trouble?

The webhook card doesn't appear: Your account hasn't been given the API and webhooks permission. Ask your courier company.
I get an address error when I click Save: The address must start with https:// (or http://) and must not contain a user name or password.
No messages arrive: Make sure the subscription is Enabled and the right events are ticked. The address must be reachable from the internet; messages aren't sent to internal (local network) addresses. Ask your developer to check that the address returns a 2xx (success) response.
The developer says "the signature doesn't match": The secret may be incomplete or copied wrongly. The whole secret (including whsec_) must be used. If unsure, get a new one with Rotate secret.
The same message arrived twice: It may be a retry; your developer should skip the repeat by checking the X-KOS-Delivery value.