Skip to content
Kirim Docs
Webhooks

Event Catalog

EventSourceX-Kirim-SourceTrigger
message.receivedMetametaCustomer sent a WhatsApp message to your connected number.
message.statusMetametaMeta delivered a status callback: sent, delivered, read, failed.
conversation.assignedKirimkirimA conversation’s assigned_to changed from one user (or null) to another.
conversation.closedKirimkirimA conversation’s status flipped to resolved.
contact.createdKirimkirimA new contact row was inserted (via inbound webhook or via POST /v1/contacts).
contact.updatedKirimkirimAn existing contact’s name, email, or metadata was patched.

Meta-sourced events

Section titled “Meta-sourced events”

For message.received and message.status, Kirim forwards the exact JSON Meta sent. Refer to the Meta WhatsApp Cloud API webhook reference for the payload schema — it never changes shape going through Kirim.

The X-Kirim-Event-Id header carries Meta’s wamid (for message.received) or status id (for message.status). Dedupe on this value.

Kirim-sourced events

Section titled “Kirim-sourced events”

conversation.assigned

Section titled “conversation.assigned”
{
  "id": "evt_01HXYZABCDEFGHJKMNPQRSTVWX",
  "type": "conversation.assigned",
  "created_at": "2026-05-23T10:00:00Z",
  "data": {
    "conversation": {
      "id": "cnv_01HXYZABCDEFGHJKMNPQRSTVWX",
      "object": "conversation",
      "status": "open"
    },
    "assignee": {
      "user_id": "usr_…",
      "team_id": "…",
      "previous_user_id": null
    }
  }
}

previous_user_id is the user the conversation was assigned to before this change (null on first assignment).

conversation.closed

Section titled “conversation.closed”
{
  "id": "evt_…",
  "type": "conversation.closed",
  "created_at": "2026-05-23T10:00:00Z",
  "data": {
    "conversation": {
      "id": "cnv_…",
      "object": "conversation",
      "status": "resolved",
      "closed_by_user_id": "usr_…"
    }
  }
}

contact.created

Section titled “contact.created”
{
  "id": "evt_…",
  "type": "contact.created",
  "created_at": "2026-05-23T10:00:00Z",
  "data": {
    "contact": {
      "id": "ctc_01HXYZABCDEFGHJKMNPQRSTVWX",
      "object": "contact",
      "phone_number": "+628111111111",
      "name": "John Doe",
      "email": null,
      "metadata": null,
      "whatsapp_account": { "phone_number": "+62 851-1760-0829" },
      "created_at": "2026-05-23T10:00:00Z",
      "updated_at": "2026-05-23T10:00:00Z"
    },
    "acquisition_source": "organic"
  }
}

contact.updated

Section titled “contact.updated”
{
  "id": "evt_…",
  "type": "contact.updated",
  "created_at": "2026-05-23T10:00:00Z",
  "data": {
    "contact": {
      "id": "ctc_…",
      "object": "contact",
      "phone_number": "+628111111111",
      "name": "John Doe (updated)",
      "email": "john@example.com",
      "...": "..."
    },
    "changed_fields": ["name", "email"]
  }
}

changed_fields lists which fields differ from the prior version — useful for routing minimal handlers.

Subscribing

Section titled “Subscribing”

Subscribe via the dashboard (Developers → Webhooks → Create) or via the API:

Terminal window
curl -X POST https://api-kckit.kirim.chat/v1/webhook_subscriptions \
  -H "Authorization: Bearer $KIRIM_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-server.example.com/kirim-webhook",
    "events": [
      "message.received",
      "message.status",
      "conversation.assigned",
      "conversation.closed",
      "contact.created",
      "contact.updated"
    ],
    "description": "n8n prod"
  }'

You may subscribe to a subset — passing ["message.received"] only fans out that event type. Update the subscribed list at any time via PATCH /v1/webhook_subscriptions/{id}.

What’s next

Section titled “What’s next”