Skip to main content
POST
Create a webhook subscription
  • Credential: an account API key. A trial key returns 401 unauthorized.
  • Line-scoped keys: the list of a line-scoped key is not applied here: the key can subscribe to any line of the account, or to all lines.
  • Test keys: a subscription created with an isnap_test_ account key is a real subscription of the account, and it receives the events of every key: see Test keys.
  • Idempotency-Key: not honored. The same request sent twice creates two subscriptions, and each event is then delivered twice to the URL. See Operations that honor the key.
  • Events: none. No event announces a new subscription: see What events do not announce.
  • Secret: the response contains the signing secret: do not log it. This operation and POST /v1/webhooks/{id}/rotate-secret are the only ones that return it.
  • Guide: Subscribing explains the URL rules, the event filter and the line filter.

Errors

The errors that every operation shares are in Errors.

Authorizations

Authorization
string
header
required

An API key created in the iSnap dashboard, or a trial key, sent as Authorization: Bearer <key>. An API key starts with isnap_live_ or isnap_test_; both act on the same account, lines and billing. A trial key acts on its trial only.

Body

application/json
url
string<uri>
required

Public https:// URL that receives the deliveries, at most 2,048 characters: a longer URL returns 500 internal_error. A URL with another scheme, or whose host is or resolves to a non-public address, or does not resolve, is refused with 400 webhook_url_not_allowed.

Example:

"https://hooks.your-domain.example/isnap"

events
enum<string>[]
required

Event types to receive: exact names such as message.received, family wildcards such as line.*, or * for every event. At least one entry: there is no default. An exact name that is not an event type returns 400 validation_failed. Not every line.* event is sent for every kind of line: line.degraded and line.capability_changed are sent for BYOD lines only, and an outage shorter than 15 minutes on a line that is not a BYOD line sends neither line.offline nor line.connected.

Minimum array length: 1

An exact event type such as message.received, a family wildcard such as line.*, or * for every event. A wildcard for a family that does not exist is accepted and matches nothing. webhook.test is never delivered through an event filter: iSnap sends it only to a suspended webhook subscription, to check whether its URL responds again.

Available options:
message.queued,
message.sent,
message.delivered,
message.read,
message.failed,
message.received,
message.scheduled,
message.cancelled,
message.fallback_triggered,
reaction.added,
reaction.received,
reaction.removed,
line.connected,
line.disconnected,
line.offline,
line.degraded,
line.apple_id_flagged,
line.quota_warning,
line.quota_exceeded,
line.capability_changed,
line.terminated,
line.variant_changed,
line.variant_scheduled,
line.variant_unscheduled,
typing_indicator.started,
typing_indicator.stopped,
trial.linked,
trial.dormant,
trial.reactivated,
trial.bind_conflict,
trial.revoked,
binding.released,
pre_order.fulfilled,
pre_order.cancelled,
macos_session.rented,
macos_session.released,
webhook.test,
*,
message.*,
reaction.*,
line.*,
typing_indicator.*,
trial.*,
binding.*,
pre_order.*,
macos_session.*,
webhook.*
Example:
line_ids
string[]

Lines to receive events for. Omitted or empty: every line, and the events tied to no line. With at least one id, the subscription receives only the events tied to one of those lines. The events of a trial are tied to the line the trial runs on: the subscription receives them only if the list contains its pool_line_id. Ids are checked for their format only: an id that matches no line is accepted and matches nothing.

Id of a line: line_ followed by 25 letters or digits.

Pattern: ^line_[0-9A-Za-z]{25}$
Example:

Response

The webhook subscription, with its signing secret.

success
enum<boolean>
required

Always true on a success response.

Available options:
true
data
object
required

A webhook subscription, in the shape that POST /v1/webhooks and GET /v1/webhooks return.

trace_id
string
required

Trace id of the request that produced this response: 32 lowercase hexadecimal characters. Quote it when you report a problem to iSnap.

request_id
string
required

Id of the request that produced this response: req_ followed by 25 letters or digits.