Kirimdev pushes events to your server via signed HTTP POSTs. You subscribe a URL once at the organisation level, pick which events you care about, and Kirimdev takes care of retries, dead-letter queueing, and signing-secret rotation.
Polling GET /v1/{phone_number_id}/messages on a timer is the wrong
answer for almost every integration:
sent → delivered →
read) happen faster than you can poll; you’ll miss intermediate
states.Webhooks invert the relationship: Kirimdev tells you when something happened, you stay idle until it does.
Every webhook POST carries an X-Kirim-Source header. Its value tells
you whether the body is Meta passthrough or a Kirimdev-native
envelope:
X-Kirim-Source: meta
Events that originated inside Meta — a customer messaged you
(message.received), or Meta confirmed a delivery status
(message.status). The body is the exact JSON Meta sent, so
any existing WhatsApp Cloud API parser keeps working unchanged.
X-Kirim-Source: kirim
Events that originated inside Kirimdev — a contact was created or
updated, a conversation got assigned or closed. These use the
Kirimdev envelope: { id, type, created_at, data }.
The two shapes coexist on the same subscription. Your handler
branches on X-Kirim-Source (or just on type after parsing) and
routes accordingly.
A webhook subscription is the binding between a URL and a list of event types you care about. Subscriptions are organisation-scoped — by default, one subscription receives events from every WhatsApp account in your org, so you don’t need one subscription per phone number.
curl -X POST https://api.kirimdev.com/v1/webhook_subscriptions \ -H "Authorization: Bearer $KIRIM_KEY" \ -H "Content-Type: application/json" \ -d '{ "url": "https://your-app.example.com/webhooks/kirim", "events": ["message.received", "message.status", "contact.created"], "description": "production listener" }'The response includes an initial_secret shown once. Store it —
it’s the signing key for every future delivery to this subscription.
If you run multiple WhatsApp numbers on the same organisation (e.g. a
“Sales” number and a “Support” number) and want to route their events
to different endpoints, add a phone_number_ids whitelist:
curl -X POST https://api.kirimdev.com/v1/webhook_subscriptions \ -H "Authorization: Bearer $KIRIM_KEY" \ -H "Content-Type: application/json" \ -d '{ "url": "https://your-app.example.com/webhooks/sales", "events": ["message.received", "message.status"], "phone_number_ids": ["106540352242922"] }'GET /v1/accounts — phone_number_id on each
row is the Meta business_phone_number_id you pass here.phone_number_ids: null to clear the filter and go
back to “all accounts”, or send an array to replace the whitelist.message.*,
conversation.*, and contact.*. Organisation-level events
(customer.*) always fire regardless of the filter.Response objects always carry phone_number_ids — null means the
subscription is unrestricted, an array is the active whitelist.
Content-Type: application/jsonUser-Agent: Kirim-Webhook/1.0X-Kirim-Source: meta # "meta" or "kirim"X-Kirim-Event: message.receivedX-Kirim-Event-Id: wamid.HBgN… # Meta wamid when source=meta, evt_<ulid> when source=kirimX-Kirim-Delivery-Id: wbd_… # Unique per delivery attemptX-Kirim-Attempt: 1 # 1-based attempt counter (1-8)X-Kirim-Signature: t=1716480000,v1=<hex>[,v1=<hex>...]X-Kirim-Event-Id.succeeded. 3xx is treated as failure — Kirimdev does
not follow redirects.delivered before sent). Treat status as a
state machine, not a sequence.X-Kirim-Event-IdBecause delivery is at-least-once, your endpoint will occasionally receive the same event twice — typically when a retry fires after your server processed the original but its 200 didn’t reach Kirimdev before the 10 s timeout.
The dedupe key is X-Kirim-Event-Id. Same id = same logical event,
regardless of attempt number or whether the delivery is a manual
replay.
import { redis } from './lib/redis.js'
app.post('/webhooks/kirim', async (req, res) => { const eventId = req.headers['x-kirim-event-id'] as string
// Atomic claim — SET NX with a 7-day TTL covers every retry window. const fresh = await redis.set(`kirim:evt:${eventId}`, '1', { EX: 60 * 60 * 24 * 7, NX: true, })
if (!fresh) { return res.status(200).send('duplicate-ack') }
await handleEvent(req.body) res.status(200).send('ok')})from fastapi import FastAPI, Request, Responseimport redis.asyncio as redis
app = FastAPI()r = redis.from_url("redis://localhost:6379")
@app.post("/webhooks/kirim")async def kirim_webhook(request: Request): event_id = request.headers["x-kirim-event-id"]
# SET NX with a 7-day TTL — covers every retry window. fresh = await r.set(f"kirim:evt:{event_id}", "1", ex=604800, nx=True) if not fresh: return Response("duplicate-ack", status_code=200)
await handle_event(await request.json()) return Response("ok", status_code=200)Meta itself retries inbound webhooks. To avoid fanning the same Meta
retry out to your subscription several times, Kirimdev dedupes
source=meta events at the publisher layer using a 24-hour claim on
the wamid. By the time an event reaches your endpoint, Meta-driven
duplicates are already filtered out.
The only dedupe scenario you need to worry about is the retry-vs-original race described above, not Meta’s own at-least-once retry pattern.
Customer → Meta → Kirimdev → signed POST → your endpoint │ │ ▼ ▼ publisher 2xx ─► succeeded dedupe + sign non-2xx / timeout ─► retry (8 attempts, ~24 h) │ ▼ dead-letter (replayable)Verifying signatures
Constant-time HMAC verification recipes for Node, Python, Ruby, Go — plus secret rotation. Read →
Event catalogue
Every event Kirimdev publishes, the source, and what triggers it. Read →
Retries & auto-disable
Backoff schedule, dead-letter queue, replay API, the 24-failure auto-disable policy. Read →
Payload examples
Copy-paste fixtures for every event, both Meta passthrough and Kirimdev-native. Read →
Subscribe to webhooks (guide)
End-to-end recipe — create a subscription, verify the first delivery, ship to production. Read →