Order webhooks in, merchant webhooks out

Order webhooks (store to Idukki)

Attribution is reconciled, not modelled: a completed order is matched back to the add-to-cart the widget recorded. That needs the store to tell Idukki about orders. Where that stands per platform:

Merchant webhooks (Idukki to you)

Register any HTTPS URL in the dashboard (Settings, Developers, Webhooks): a Make.com custom webhook, an n8n node, a Zapier catch hook or your own endpoint. Pick the events, set an optional signing secret. Every delivery is a POST with the same envelope.

POST https://your-endpoint.example/idukki
content-type: application/json
x-idukki-signature: sha256=<hex HMAC-SHA256 of the exact body, when a secret is set>

{
  "event": "rights.granted",
  "businessId": "YOUR_BGUID",
  "payload": { … },
  "timestamp": "2026-09-07T10:15:02.412Z"
}

import { createHmac, timingSafeEqual } from 'node:crypto'

export function verifyIdukki(rawBody, header, secret) {
  const expected = 'sha256=' + createHmac('sha256', secret).update(rawBody, 'utf8').digest('hex')
  return header && header.length === expected.length && timingSafeEqual(Buffer.from(header), Buffer.from(expected))
}

Delivery rules

• Fire-and-forget from the product’s hot paths: a slow or failing endpoint never blocks a lead capture, a rights decision or an order.
• Eight-second timeout per delivery. Return a 2xx quickly and do the work asynchronously.
• A 404 or 410 from your endpoint prunes the subscription (the Make.com convention for a deleted scenario). Re-add it in the dashboard.
• The last delivery time and status are shown per webhook in the dashboard.

Event catalogue

Two families. Product events come from the central dispatcher and are what Slack, Zapier, Teams, the helpdesk integrations and outbound webhooks all receive. Widget events are the ones the dashboard’s webhook screen lists for widget and experiment lifecycle.

Signed API webhooks (rolling out)

A second, stricter channel sent by the Idukki API itself. Each delivery is signed over a timestamp and the raw body, retried on failure, and logged per delivery. It is managed through GraphQL (createOutboundWebhook, updateOutboundWebhook, deleteOutboundWebhook, rotateOutboundWebhookSecret, testOutboundWebhook, outboundWebhooks, outboundWebhookDeliveries), up to 10 webhooks per account. The setup guide at /help/webhooks-guide walks through it.

POST https://your-endpoint.example/idukki
Content-Type: application/json
X-Idukki-Event: ugc.created
X-Idukki-Delivery: 1234
X-Idukki-Signature: t=<unix seconds>,v1=<hex HMAC-SHA256(secret, t + "." + raw body)>

{ "id": "evt_1234", "type": "ugc.created", "createdAt": "2026-10-04T10:15:02.412Z", "data": { … } }

import { createHmac, timingSafeEqual } from 'node:crypto'

export function verifyIdukkiWebhook(rawBody, signatureHeader, secret, toleranceSeconds = 300) {
  if (!signatureHeader) return false
  const parts = Object.fromEntries(
    signatureHeader.split(',').map((p) => p.trim().split('=')).filter((p) => p.length === 2),
  )
  const t = Number(parts.t)
  if (!Number.isInteger(t) || !parts.v1) return false
  if (Math.abs(Math.floor(Date.now() / 1000) - t) > toleranceSeconds) return false
  const expected = createHmac('sha256', secret).update(`${t}.${rawBody}`).digest('hex')
  const a = Buffer.from(expected, 'utf8')
  const b = Buffer.from(parts.v1, 'utf8')
  return a.length === b.length && timingSafeEqual(a, b)
}

• Any 2xx is delivered; 10-second timeout; redirects are not followed.
• Failures retry with the same body at the earliest 1 min, 5 min, 30 min, 2 h and 6 h later: six attempts, then failed. X-Idukki-Delivery and the envelope id stay the same across retries, so de-duplicate on them.
• https only. Private, loopback, link-local, CGNAT and reserved addresses, localhost and internal host names are refused, and every connection re-checks the resolved address.
• The whsec_ secret is returned once, on create and on rotate. Payloads never carry a shopper email or phone.
• Not the same format as the dashboard webhooks above, which sign sha256=<hex> over the body alone and use the event names in the catalogue above. Tell them apart by the signature header value.

Webhooks Idukki receives from platforms

For completeness, the inbound routes on the API that platforms call. You do not configure these; the Shopify app and the Stripe integration register them.