Create webhook subscription

This page documents the canonical HTTP contract. Switch to the CLI example when you want the operator workflow.

Creation inserts the subscription and returns the new signing_secret once. Save it securely; later reads omit it. Filters and metadata default to empty objects. Unknown event names return 400.

Delivery is asynchronous. The compact JSON event body is signed with HMAC-SHA256 over timestamp + "." + body, using a v1=<hex> signature. Headers include X-SmartTable-Webhook-Id, X-SmartTable-Webhook-Timestamp, X-SmartTable-Webhook-Signature, X-SmartTable-Event-Type, X-SmartTable-Webhook-Delivery-Id, and Idempotency-Key. A 2xx response succeeds; every other HTTP status or request exception schedules exponential retry until the attempt limit.

Body parameters

urlrequired
string
Absolute http(s) URL without embedded username/password. Production requires HTTPS; public-host restrictions apply in production.
eventsrequired
array<string>
At least one supported event or family. Values are trimmed, lowercased, deduplicated, then validated against the event catalog.
enabled · optional
boolean
Set false to create paused.
filters · optional
object
Delivery matching filters: exact nested paths plus conditions using field/path/key, operator, and value/expected/equals. Operators: eq, neq, gt, gte, lt, lte, exists, not_exists, in, not_in, contains, not_contains; condition mode is and (default) or or.
metadata · optional
object
Opaque metadata for client use.
retryPolicy · optional
object
max_attempts 1-50 (default 8), base_delay_seconds 1-3600 (default 10), max_delay_seconds 1-86400 (default 900 and raised to at least base), timeout_seconds 1-120 (default 10). Values are clamped; invalid values fall back to defaults.

Name	Type	Description
urlrequired	string	Absolute http(s) URL without embedded username/password. Production requires HTTPS; public-host restrictions apply in production.
eventsrequired	array<string>	At least one supported event or family. Values are trimmed, lowercased, deduplicated, then validated against the event catalog.
enabled	boolean	Set false to create paused.
filters	object	Delivery matching filters: exact nested paths plus conditions using field/path/key, operator, and value/expected/equals. Operators: eq, neq, gt, gte, lt, lte, exists, not_exists, in, not_in, contains, not_contains; condition mode is and (default) or or.
metadata	object	Opaque metadata for client use.
retryPolicy	object	max_attempts 1-50 (default 8), base_delay_seconds 1-3600 (default 10), max_delay_seconds 1-86400 (default 900 and raised to at least base), timeout_seconds 1-120 (default 10). Values are clamped; invalid values fall back to defaults.

Errors

Status	Meaning
400	Invalid URL or unsupported/empty events.
401	Invalid API key or missing auth.
403	Missing webhooks:write scope.
422	Missing or malformed required body fields.

Example

bash

curl -X POST "https://app.autotouch.ai/api/webhook-subscriptions" \
    -H "Authorization: Bearer stk_your_key_id.your_secret" \
    -H "Content-Type: application/json" \
    -d '{
      "url":"https://example.com/webhooks/smart-table",
      "events":["bulk_job.*","lead.*"]
    }'

Request body

json

{
    "url": "https://example.com/webhooks/smart-table",
    "events": [
      "bulk_job.*",
      "lead.created",
      "lead.status_changed",
      "sequence_enrollment.created",
      "task.created"
    ],
    "enabled": true,
    "filters": {"source": "api"},
    "metadata": {"env": "prod"},
    "retryPolicy": {
      "max_attempts": 8,
      "base_delay_seconds": 10,
      "max_delay_seconds": 900,
      "timeout_seconds": 10
    }
  }

Response example

json

{
    "success": true,
    "subscription": {
      "id": "67c88a24b4dd8f2d4999f912",
      "organization_id": "67b03b8f0af6e6aaf0ec4f40",
      "url": "https://example.com/webhooks/smart-table",
      "enabled": true,
      "status": "active",
      "events": ["bulk_job.*", "lead.created", "lead.status_changed", "sequence_enrollment.created", "task.created"],
      "signing_secret": "stwhsec_...returned_once...",
      "signing_secret_last4": "A7m2"
    }
  }