Skip to content
Start free Sign in

Receive webhooks

Agency plan

Last updated

Available on the Agency plan

This feature is included in the Agency plan and the plans above it. See pricing

A webhook is a message Kukie.io sends to your server when something happens in your organisation, such as a cookie scan that ended. Your software then does not have to ask the API again and again. This guide shows how to create an endpoint, check that a message really comes from Kukie.io, and handle retries and duplicates.

The API is included on the Agency and Unlimited plans. See the pricing page for what each plan includes.

Before you start

  • An API key with the webhooks:write permission. Only a key that reaches all sites can have it, because endpoints and events belong to the whole organisation, not to single sites. The guide to keys and permissions shows how to create one.
  • An address on your server that accepts POST requests. It must start with https://, use the standard port, be reachable from the public internet, and contain no user name, password or fragment. Write an internationalised domain name in its xn-- form.

Create an endpoint

An endpoint is the address Kukie.io sends events to, with the list of event types it wants. Use ["*"] for every type.

curl -X POST "https://api.kukie.io/v1/webhook-endpoints" \
  -H "Authorization: Bearer $KUKIE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/kukie/webhooks","enabled_events":["scan.completed","scan.failed"]}'

The answer is the new endpoint. Its id starts with whk_, and its secret starts with whsec_. Store the secret in a secret manager: Kukie.io shows it only in this answer and in the answer to a rotation. If you send the request again with the same Idempotency-Key, the answer comes back with secret set to null.

An organisation can have up to 10 endpoints. Endpoints that are turned off count too.

When you create an endpoint or change its url, Kukie.io checks the address. Your organisation can check one address or send one test event at a time, and Kukie.io checks only a few addresses and sends only a few test events at once for all customers. While another check or test of your organisation is running, or Kukie.io is at that limit, the request answers 429 concurrency_limited with Retry-After: 10. Wait, then send it again.

What Kukie.io sends

Each delivery is one POST request with a JSON body:

POST {your endpoint's address}
Content-Type: application/json
User-Agent: Kukie-Webhooks/1.0 (+https://kukie.io/docs/api)
webhook-id: evt_01kab3x9p7q2r4s6t8v0w2y4z6
webhook-timestamp: 1763461230
webhook-signature: v1,K5oZfzN95Z9UVu1EsfQmfVNQhnkZ2pj9o9NDN/H/pI4=
  • webhook-id is the event's id. It stays the same on every attempt to deliver that event.
  • webhook-timestamp is the time of this attempt, in seconds since 1 January 1970 (UTC). Each attempt has a new one.
  • webhook-signature holds one or more signatures, separated by a space. Each starts with v1,.

The headers and the signature follow the Standard Webhooks specification. The body is at most 20,000 bytes.

A scan.completed body, formatted here for reading (it is sent as compact JSON):

{
    "id": "evt_01kab3x9p7q2r4s6t8v0w2y4z6",
    "object": "event",
    "type": "scan.completed",
    "timestamp": "2026-11-18T10:20:30Z",
    "api_version": "v1",
    "data": {
        "object": "scan",
        "id": "0b6f6a52-7c1e-4d0a-9f3b-2a8f5e1c4d7b",
        "site": {
            "id": "5d2c8a1e-3f4b-4c6d-8e9f-0a1b2c3d4e5f",
            "external_id": "customer-4821"
        },
        "status": "completed",
        "completed_at": "2026-11-18T10:20:04Z"
    }
}

timestamp is when Kukie.io recorded the event. Read type first, then data. New members and new event types can be added at any time, so ignore what your software does not know, and do not rely on the order of the members inside data.

Answer the request

  • Answer with any 2xx status within 10 seconds. Kukie.io ignores what the body of your answer says, so keep it short: an answer with a body above 65,536 bytes counts as a failure.
  • Do slow work after you answer. Store the message, answer, and process it afterwards.
  • Kukie.io does not follow redirects. A 3xx answer counts as a failure.

Verify the signature

Anyone who knows your endpoint's address can send it a request, so check the signature before you trust a message:

  1. Read the raw body of the request, before your framework parses the JSON. The signature covers the exact bytes that were sent.
  2. Refuse the message if webhook-timestamp is more than 5 minutes from your server's time. This stops someone who recorded an old message from sending it again.
  3. Take the part of your secret after whsec_ and decode it from base64. That is the signing key. Refuse the message if the key is empty, for example because the secret is missing from your server's settings: a signature made with an empty key proves nothing.
  4. Join the webhook-id, the webhook-timestamp and the body with full stops: {id}.{timestamp}.{body}.
  5. Compute the HMAC-SHA256 of that text with the signing key, and encode the result as base64.
  6. Split webhook-signature at the spaces and accept the message if any entry equals v1, followed by your result. Compare with a constant-time function.

PHP

$headers holds the request's headers with lower-case names, and $body the raw body, for example from file_get_contents('php://input').

function verifyKukieWebhook(string $secret, array $headers, string $body, ?int $now = null): bool
{
    $id = $headers['webhook-id'] ?? '';
    $timestamp = $headers['webhook-timestamp'] ?? '';
    $signatures = $headers['webhook-signature'] ?? '';

    // Refuse a message whose timestamp is more than 5 minutes from now.
    if ($id === '' || ! ctype_digit($timestamp) || abs(($now ?? time()) - (int) $timestamp) > 300) {
        return false;
    }

    // The signing key is the base64-decoded part of the secret after "whsec_".
    $key = base64_decode(substr($secret, strlen('whsec_')), true);
    if ($key === false || $key === '') {
        return false;
    }

    $expected = 'v1,' . base64_encode(hash_hmac('sha256', "{$id}.{$timestamp}.{$body}", $key, true));

    // The header can hold several signatures, separated by a space. One match is enough.
    foreach (explode(' ', $signatures) as $signature) {
        if (hash_equals($expected, $signature)) {
            return true;
        }
    }

    return false;
}

Node.js

headers is the request's headers object, whose names Node.js already gives in lower case, and body the raw body as a string. With Express, read it with express.raw({ type: 'application/json' }) and pass req.body.toString('utf8').

const crypto = require('node:crypto');

function verifyKukieWebhook(secret, headers, body, now = Math.floor(Date.now() / 1000)) {
  const id = headers['webhook-id'];
  const timestamp = headers['webhook-timestamp'];
  const signatures = headers['webhook-signature'];

  // Refuse a message whose timestamp is more than 5 minutes from now.
  if (!id || !signatures || !/^\d+$/.test(timestamp || '') || Math.abs(now - Number(timestamp)) > 300) {
    return false;
  }

  // The signing key is the base64-decoded part of the secret after "whsec_".
  const key = Buffer.from(secret.slice('whsec_'.length), 'base64');
  if (key.length === 0) {
    return false;
  }

  const expected = Buffer.from(
    'v1,' + crypto.createHmac('sha256', key).update(`${id}.${timestamp}.${body}`).digest('base64')
  );

  // The header can hold several signatures, separated by a space. One match is enough.
  return signatures.split(' ').some((signature) => {
    const given = Buffer.from(signature);
    return given.length === expected.length && crypto.timingSafeEqual(given, expected);
  });
}

The last parameter of both functions is the current time and is there for your tests. Leave it out in production.

You can also use one of the Standard Webhooks reference libraries, which exist for PHP, JavaScript and other languages. They are not written or maintained by Kukie.io.

Rotate the secret

curl -X POST "https://api.kukie.io/v1/webhook-endpoints/{id}/rotate-secret" \
  -H "Authorization: Bearer $KUKIE_API_KEY"

The answer holds the new secret. For 24 hours after a rotation, every delivery carries two signatures, one made with the new secret and one with the old. So your server keeps verifying while you change the secret it uses, as long as it accepts any of the signatures, as the samples above do. After that, only the new secret signs.

Send a test event

curl -X POST "https://api.kukie.io/v1/webhook-endpoints/{id}/test" \
  -H "Authorization: Bearer $KUKIE_API_KEY"

Kukie.io sends one webhook.test event to the endpoint, whatever event types it wants, and waits for the answer. The API's answer tells you whether it was delivered, with delivered, status_code and duration_ms. The body of a test event looks like this:

{
    "id": "evt_01kab3x9p7q2r4s6t8v0w2y4z6",
    "object": "event",
    "type": "webhook.test",
    "timestamp": "2026-11-18T10:20:30Z",
    "api_version": "v1",
    "data": {
        "webhook_endpoint": {
            "id": "whk_01kab2m4n6p8q0r2s4t6v8w0x2"
        }
    }
}
  • A test event is sent once. It is never retried, and a failed test never turns an endpoint off.
  • You can send 5 test events a minute to one endpoint and 60 an hour for the organisation, one at a time. While another test or address check of your organisation is running, or while Kukie.io is sending as many tests and checking as many addresses as it allows at once, the API answers 429 concurrency_limited with Retry-After: 10.
  • A test of an endpoint that is turned off answers 409 conflict.

Event types

  • scan.completed: a cookie scan of a site ended with results. data.status is completed, or completed_with_errors when some pages could not be scanned.
  • scan.failed: a cookie scan of a site ended with no results.
  • site.created: a site was added to your organisation, in the dashboard or through the API.
  • site.deleted: a site was deleted, in the dashboard or through the API.
  • site.installation_verified: a cookie scan found the Kukie.io script on the site's own domain. It is sent again when that proof was lost and a later scan finds the script again.
  • report.ready: the scan report of a completed scan is ready. data.links holds the addresses of the report as JSON and as a PDF, which you read with an API key that has the reports:read permission and reaches the site. A PDF is made the first time it is asked for, so data.pdf.status is usually not_requested. Scan reports are not available yet, so this event is not sent until Kukie.io announces them in the API changelog.

Kukie.io looks for scans that ended, new sites and newly verified installations once a minute, so these events follow what happened by a minute or two. site.deleted is recorded when the site is deleted, and report.ready when the report is stored, which is usually seconds after the scan ends. A scan that ended before scan reports were available gets its report, and this event, the first time its report is asked for.

The data of scan.completed and scan.failed has the members of the example above. data.id is the scan's id and data.site.id the site's id, the ones the API uses in its addresses. The data of the three site events describes the site:

"data": {
    "object": "site",
    "id": "5d2c8a1e-3f4b-4c6d-8e9f-0a1b2c3d4e5f",
    "external_id": "customer-4821"
}

external_id is the value you gave the site, or null. A site that moves to your organisation from another one sends no event.

The data of report.ready names the report and where to read it:

"data": {
    "object": "scan_report",
    "site": { "id": "5d2c8a1e-3f4b-4c6d-8e9f-0a1b2c3d4e5f", "external_id": "customer-4821" },
    "scan": { "id": "9b7e6d5c-4a3b-4c2d-9e1f-0a9b8c7d6e5f" },
    "schema_version": 1,
    "content_hash": "sha256:3f1a...",
    "built_at": "2026-11-20T10:20:30Z",
    "pdf": { "status": "not_requested" },
    "links": {
        "json": "https://api.kukie.io/v1/sites/5d2c8a1e-3f4b-4c6d-8e9f-0a1b2c3d4e5f/scans/9b7e6d5c-4a3b-4c2d-9e1f-0a9b8c7d6e5f/report",
        "pdf": "https://api.kukie.io/v1/sites/5d2c8a1e-3f4b-4c6d-8e9f-0a1b2c3d4e5f/scans/9b7e6d5c-4a3b-4c2d-9e1f-0a9b8c7d6e5f/report/pdf"
    }
}

content_hash is the report's own content_hash. When a report is built again with other content, a new report.ready event is sent with the new hash, and a PDF made from the earlier report is no longer served.

Retries

When a delivery fails, Kukie.io tries again up to 9 times, 10 attempts in all. The waits after each failed attempt are 5 seconds, 5 minutes, 30 minutes, 2 hours, 5 hours, 10 hours, 14 hours, 20 hours and 24 hours. They add up to 75 hours, 35 minutes and 5 seconds, about 3 days, and each wait can be up to 10% longer. Deliveries are sent once a minute, so a short wait lasts until the next minute.

  • When your server cannot be reached, takes longer than 10 seconds, or answers with a 5xx, a 3xx or 429 status, Kukie.io waits with every delivery to that endpoint until the failed one is due again. Later events wait in order.
  • When your server answers with another 4xx status, only that delivery is retried and later events are still sent. After 5 failed attempts in a row, the endpoint rests for 15 minutes.
  • Kukie.io does not read a Retry-After header in your answer.

When Kukie.io turns an endpoint off

  • At once, when your server answers a delivery with 410 Gone.
  • When a delivery has failed all 10 attempts and the endpoint's first failure since its last successful delivery was 75 hours, 35 minutes and 5 seconds or more ago.

Kukie.io then stops sending to the endpoint, cancels the deliveries that were waiting for it, and emails the owner and every admin of your organisation. Events are still recorded, so you can read what you missed, as described under Read events through the API.

Your organisation gets at most 10 of these emails in the 24 hours that start with the first of them. When more endpoints are turned off in that time, the email about each of them follows when the 24 hours end.

To turn an endpoint back on, fix your server, then set its status:

curl -X PATCH "https://api.kukie.io/v1/webhook-endpoints/{id}" \
  -H "Authorization: Bearer $KUKIE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status":"enabled"}'

Deliveries that were cancelled are not sent again. You can turn an endpoint off yourself with "status": "disabled". Kukie.io sends no email for that.

Duplicates and order

  • An event can arrive more than once, for example when your server did the work but its answer was lost. Keep the webhook-id of each message you have handled, and skip a message whose id you already have.
  • Events can arrive out of order. Use the times inside the event, not the order of arrival.
  • An endpoint gets only events recorded while it existed, was turned on and wanted that type.

Read events through the API

Kukie.io records every event of your organisation and keeps it for 30 days, whether or not you have an endpoint. Reading events needs the webhooks:read permission:

curl "https://api.kukie.io/v1/events?type=scan.completed&from=2026-11-17T00:00:00Z" \
  -H "Authorization: Bearer $KUKIE_API_KEY"

from must be a time in the last 30 days. Each event in the list has the same members as the body of its delivery, and its id is the delivery's webhook-id. Use this list to catch up after your server was down, or to check from time to time that no event was missed. The list comes in pages, as described in Read lists page by page.

Check it worked

Send a test event. When the answer says "delivered": true, your server answered with a 2xx status. Then check on your server that the signature of that message verifies. Owners and admins also see the endpoints and their latest deliveries under Webhooks on the API keys page of your Kukie.io account, and can delete an endpoint there, also when your plan no longer includes the API.

Was this helpful?

Listed on