Create a webhook
create_webhookCreate a signed webhook so Parley POSTs real-time events—messages, reactions, deletions—to your URL instead of polling the inbox.
Instructions
Have Parley POST to a URL the moment something happens on one linked number, instead of polling read_inbox. Each webhook belongs to one number; add one per number to hear from several. Events: message.received (a message came in from someone else); message.sent (the account sent a message (from its phone, or through Parley)); reaction.added (someone (or the account) reacted to a message, or changed their reaction); reaction.removed (someone (or the account) took their reaction back); message.deleted (a message was deleted for everyone). Only real, live changes are sent: never history, backfills, or a message seen twice; chats the account holder ignored never send. Each request is a signed JSON POST: { id, type, created_at, sent_at, connection: { id, channel, account }, data }; for messages the text is at data.message.text (the answer's payload_format has every event's shape and an example: build the receiver from it). If the receiver checks who's calling with a key of its own (an Authorization header or API key its setup gave you), pass it in headers. The answer carries the signing secret: keep it, it isn't shown again (update_webhook with rotate_secret makes a new one). The account holder sees and can change every webhook on that number's page on the Parley dashboard. At most 10 per number.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | A public https URL (not a private, local or internal address). A key in it is fine (?token=…, or one in the path): the URL is kept sealed and shown back with its keys masked. user:password@ before the host is sent as an Authorization: Basic header instead. | |
| events | No | Which events to send. Default: all of them. | |
| headers | No | Headers of your own to send on every request, as { name: value }, for a receiver that checks who's calling: e.g. { "Authorization": "Bearer <key>" } or { "X-Api-Key": "<key>" }, exactly as the receiver's setup gives them. Sent alongside Parley's own headers and signature; kept sealed, and only each name and the value's last 4 characters are ever shown back. At most 10; Parley's own (Parley-*, Webhook-*, Content-Type, User-Agent, Host…) can't be set. | |
| description | No | What it's for, shown on the dashboard. | |
| connection_id | No | Which of your accounts: a connection id from list_connections, or the account's number. Optional when only one account fits. The webhook hears only from this number. |