Prerequisites
- Understanding of Button webhooks or Modal submissions
- An endpoint URL and optional auth (API key, Bearer, Basic)
Creating webhook destinations
Basic destination
- Go to Integrations → Webhooks
- Click Create Webhook Destination
- Set Name (e.g. “Support Ticket API”), URL (e.g.
https://api.example.com/tickets), Method (POST, PUT, or PATCH), and optional Description
With authentication
Add headers for secured endpoints:- Bearer:
Authorization: Bearer sk_live_abc123... - API key:
X-API-Key: your-api-key - Basic:
Authorization: Basic base64(username:password) - Custom headers: Any key/value (e.g.
Content-Type: application/json,X-Request-ID: {{request_id}})
Destination properties
| Property | Description | Required |
|---|---|---|
| name | Friendly name | Yes |
| url | Full webhook endpoint URL | Yes |
| method | POST, PUT, PATCH | Yes |
| description | What this webhook does | No |
| headers | HTTP headers (auth, custom) | No |
| timeout_ms | Request timeout (default: 5000) | No |
| retry_config | Retry behavior | No |
Payload templating
In the destination or in the button/modal action, define a payload template (JSON) with placeholders. Placeholders are replaced with interaction and template data when the webhook is sent. Examples:- Template data:
"expense_id": "{{expense.id}}","approved_by": "{{user.email}}" - Interaction:
"user_id": "{{interaction.user_id}}","button_value": "{{interaction.button_value}}" - Slack context:
"channel": "{{slack.channel_id}}","message_ts": "{{slack.message_ts}}"
Retry configuration
Configure retries for failed webhooks (e.g. 5xx, timeouts, connection failures). Typical settings:max_retries, initial_delay_ms, max_delay_ms, backoff_multiplier. 4xx errors are not retried.
For endpoints that are not idempotent, set max_retries: 0 or disable retries. When retries are on, include an idempotency_key in the payload (e.g. {{interaction.id}}) so your API can deduplicate.
Monitoring webhooks
View webhook activity and debug failures on the Usage page:- Filter by date, template, status (success/failed/timeout)
- For each call: request payload, response status, response body, error message, processing time, retry attempts