Webhook Automation

Ingest external events into a workspace and convert them into tasks, docs, and activity.

Endpoint contract (v1)

POST /api/v1/workspaces/webhooks/ingest?workspaceId=<workspaceId>&webhookId=<webhookId>
Headers:
  X-Sutraha-Webhook-Secret: <secret>  (required)
  X-Provider-Event-Id: <provider event id> (optional, for idempotency)
  Content-Type: application/json

Success:
  202 Accepted

Errors:
  401/403 secret invalid
  404 webhook not found
  413 payload too large (>262144 bytes)
  429 rate limit exceeded

Action templates

create_task: create task from payload mapping.
create_document: create note document from payload.
log_activity: append webhook event in activity feed.
task_and_nudge_main: create task and notify main agent.

Quick test with curl

curl -X POST "https://<convex-site>.convex.site/api/v1/workspaces/webhooks/ingest?workspaceId=<workspaceId>&webhookId=<webhookId>" \
  -H "Content-Type: application/json" \
  -H "X-Sutraha-Webhook-Secret: <secret>" \
  -H "X-Provider-Event-Id: evt-001" \
  -d '{"event":{"type":"demo.webhook"},"payload":{"message":"hello"}}'

Next guides

Security guide Provider recipes

Recommended

Use provider event IDs whenever available so duplicate deliveries do not create duplicate tasks/documents.