Webhooks overview

​

Terms

​

Subscribing

• A subscription belongs to your account. Every API key of the account reads and changes every subscription of the account.
• A line-scoped key is not restricted on webhook operations. It creates subscriptions for all lines, reads every delivery record and reads the events feed of every line of the account, message content included. Do not treat a line-scoped key as a boundary here.
• An isnap_test_ account key is not a separate test environment: it acts on the same account, lines and billing as an isnap_live_ key. Both kinds of key see the same subscriptions, and an event carries no mark of the key that caused it. See Test keys.
• A trial key cannot call a webhook operation: the API returns 401 unauthorized.

​

URL rules

​

Event filter

• There is no default filter. A missing or empty events returns 400 validation_failed.
• An exact name that is not an event type returns 400 validation_failed.
• A wildcard is accepted for any lowercase family name, including a family that does not exist. It then matches nothing: check the spelling of a wildcard yourself.
• The API sets no maximum number of entries, and accepts duplicates.
• Subscribing to webhook.test or webhook.* has no effect: webhook.test is sent only as a probe, whatever the filter.

​

Line filter

• Events that carry no line id never reach the subscription: pre_order.cancelled, macos_session.rented and macos_session.released. The two macos_session.* events stay out even when the session runs one of the listed lines.
• trial.* events, and the message, reaction and typing events of a trial, are tied to the line the trial runs on (pool_line_id). The subscription receives them only if it lists that line id.
• pre_order.fulfilled is tied to the line the pre-order produces. The pre-order does not give you that line id beforehand: receive pre-order events on a subscription without a line filter.

​

What your endpoint must do

• Serve HTTPS on a public host. The certificate must be one a standard HTTP client accepts. A self-signed or expired certificate is a failed attempt.
• Verify the signature on the raw body. Compute the signature over the bytes you received, before any JSON parsing: see Verifying signatures. iSnap promises no User-Agent value and no list of source addresses: a delivery is authenticated by its signature, and by nothing else.
• Return a 2xx status within 10 seconds. Any status from 200 to 299, received within 10 seconds, is a success. iSnap does not interpret the response body, but it keeps its first 1,024 characters in the delivery record, readable with any API key of your account for at least 72 hours, or until you delete the subscription: return an empty body. Every other outcome is a failed attempt, retried except after a 410: see Retries.
• Do not redirect. iSnap never follows a redirect. A 3xx response is a failed attempt.
• Respond first, process later. Store the event, return 2xx, then do the work. A response that arrives after 10 seconds counts as a failure even if you processed the event, and the event is then delivered again.
• Deduplicate, and do not rely on order. Deduplicate on event_id. Delivery order is not guaranteed. Order events by the timestamps inside data, not by arrival. See Duplicates and Order.
• Accept what you do not handle. Return 2xx for an event type you do not handle, and for a probe (webhook.test). Ignore response fields, enum values and event types you do not know.

​

What a delivery contains

​

Lines that change owner

• message.sent, message.delivered, message.read, message.failed and message.fallback_triggered about a message that an earlier owner sent, each with the full message: its text, its handles, its attachment file names and its metadata;
• reaction.received and reaction.removed about a reaction of a contact to an earlier message;
• the message.read events of a mark-read: a POST /v1/chats/{chat_id}/read by the next owner also marks read the inbound messages that an earlier owner had not marked read, and sends each of them in full.

• a message.* event whose data.message.created_at is earlier than the time the line became yours;
• a reaction.* event whose parent_message_id is not a message that you sent or received on the line.

​

Subscription states

​

Example: create a subscription

curl -sS -X POST https://api.isnap.ai/v1/webhooks \
  -H "Authorization: Bearer $ISNAP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://hooks.your-domain.example/isnap",
    "events": ["message.*", "line.*"]
  }'

import { APIError, ISnapClient } from '@isnap/sdk'

const client = new ISnapClient({ apiKey: process.env.ISNAP_API_KEY ?? '', maxRetries: 2 })

try {
  // maxRetries: 0, because a retry after a lost response would create a second subscription.
  const subscription = await client.webhooks.create(
    { url: 'https://hooks.your-domain.example/isnap', events: ['message.*', 'line.*'] },
    { maxRetries: 0 }
  )
  console.log(subscription.id)
  // Store subscription.secret in your secret manager now: no other call returns it.
} catch (err) {
  if (err instanceof APIError && err.code === 'webhook_url_not_allowed') {
    console.error(`URL refused: ${err.issues?.[0]?.code}`)
  } else {
    throw err
  }
}

import os

import requests

API = "https://api.isnap.ai"
HEADERS = {"Authorization": f"Bearer {os.environ['ISNAP_API_KEY']}"}

response = requests.post(
    f"{API}/v1/webhooks",
    headers=HEADERS,
    json={
        "url": "https://hooks.your-domain.example/isnap",
        "events": ["message.*", "line.*"],
    },
    timeout=30,
)
body = response.json()
if response.status_code != 201:
    error = body["error"]
    if error["code"] == "webhook_url_not_allowed":
        raise SystemExit(f"URL refused: {error['issues'][0]['code']}")
    raise SystemExit(f"{error['status']} {error['code']} (trace_id {body['trace_id']})")

subscription = body["data"]
print(subscription["id"])
# Store subscription["secret"] in your secret manager now: no other call returns it.

{
  "success": true,
  "data": {
    "id": "wh_3Kp8Rn9Fh2Lm5Qx7Vw1Yz4Bc6",
    "url": "https://hooks.your-domain.example/isnap",
    "events": ["message.*", "line.*"],
    "line_ids": null,
    "active": true,
    "failure_count": 0,
    "last_success_at": null,
    "last_failure_at": null,
    "created_at": "2026-10-08T14:22:57.392Z",
    "secret": "whsec_00112233445566778899aabbccddeeff00112233445566778899aabbccddeeff"
  },
  "trace_id": "0af7651916cd43dd8448eb211c80319c",
  "request_id": "req_5Hn2Wq8Kd3Lx7Vb1Zt9Rm4Yc6"
}

​

Next steps