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:

Integration alert webhooks (Idukki to you)

The older alert webhooks live under Settings, Integrations, on the Webhooks tab. Register any HTTPS URL there. Make.com, n8n, Zapier or your own endpoint all work. Pick the events, set an optional signing secret. Every delivery is a POST with the same envelope. For new work, use the signed webhooks below.

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 webhooks: Settings, Webhooks

In the dashboard, open Settings, then Webhooks. Add an https endpoint and pick from five events. You can send a test, rotate the secret and read the delivery log there. Each delivery is signed with X-Idukki-Signature over a timestamp and the raw body. Failed deliveries are retried. Up to 10 webhooks per account.

To manage them from code, use GraphQL: createOutboundWebhook, updateOutboundWebhook, deleteOutboundWebhook, rotateOutboundWebhookSecret, testOutboundWebhook, outboundWebhooks and outboundWebhookDeliveries. The setup guide at /help/webhooks-guide walks through both.

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.