Per-account filter for webhook subscriptions

Released: July 3, 2026

Per-account filter on webhook subscriptions Added

Webhook subscriptions used to fire for every WhatsApp account in the organisation — one subscription, all numbers. That was fine for a single-number org, but customers running a “Sales” number and a “Support” number on the same organisation had no way to route their events to different endpoints without filtering server-side.

You can now scope a subscription to a whitelist of Meta business_phone_number_id values on create or update:

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"]
  }'

• Omit phone_number_ids (or send null on update) to keep the current behaviour — the subscription fires for every account in the org.
• Send an array to whitelist specific numbers. Discover the ids via GET /v1/accounts (phone_number_id column on each row).
• Send null on PATCH to clear an existing filter and go back to “all accounts”.

Every existing subscription keeps working unchanged — the field defaults to unrestricted, so no migration is required on your side.

Which events the filter applies to

The filter only affects events that originate from a specific WhatsApp account:

• message.received, message.status, message.sent
• conversation.assigned, conversation.closed
• contact.created, contact.updated, contact.identity_updated

Organisation-level events (customer.created, customer.updated, customer.archived, customer.onboarded, customer.setup_link.*) ignore the filter and fire for every subscription regardless. Those events aren’t tied to a phone number, so scoping them by phone number wouldn’t be meaningful.

Response shape

Every webhook subscription response now includes a phone_number_ids field:

{
  "id": "wbs_...",
  "object": "webhook_subscription",
  "url": "https://your-app.example.com/webhooks/sales",
  "events": ["message.received"],
  "phone_number_ids": ["106540352242922"],
  "status": "active",
  ...
}

null = unrestricted (fires for every account). An array = the whitelist, in insertion order.

Validation

• Each value must match ^\d{6,20}$ (Meta’s business_phone_number_id shape).
• Up to 50 ids per subscription.
• Every id must resolve to an account in the calling organisation — otherwise the request fails with invalid_field_value (HTTP 422).

SDK Changed

@kirimdev/sdk picks up the new field via the fresh openapi.json snapshot. webhookSubscriptions.create() and webhookSubscriptions.update() accept phone_number_ids; the response object exposes it too. Zero migration for existing callers that don’t set the field.

// Scope on create
await kirim.webhookSubscriptions.create({
  url: 'https://your-app.example.com/webhooks/sales',
  events: ['message.received', 'message.status'],
  phone_number_ids: ['106540352242922'],
})

// Clear the filter on an existing subscription
await kirim.webhookSubscriptions.update('wbs_...', {
  phone_number_ids: null,
})

Dashboard Added

Developers → Webhooks now includes a multi-select for WhatsApp accounts on the create dialog. Leave it empty to receive events from every connected account (the current behaviour). The subscription detail drawer shows the active filter; changing it currently means recreating the subscription — inline edit is planned but not shipped in this release.

Read the webhooks overview →