Skip to content
Synthetic Users

Webhooks API

See the webhooks guide for the HMAC signature format, retry policy, and event payloads.

Available events: run.completed, run.failed, run.partial, session.completed, session.failed.

POST /webhooks

Provide your own secret (16+ characters) or leave it out and we generate one. Either way, the secret is returned only once in this response.

Terminal window
curl -s -X POST "$API_URL/webhooks" \
  -H "Authorization: Bearer $SYNTHUSERS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-app.example.com/synthusers/webhook",
    "events": ["run.completed", "run.failed", "session.completed"]
  }'

Response (secret returned once)

{
  "id": "wh_01H...",
  "url": "https://your-app.example.com/synthusers/webhook",
  "events": ["run.completed", "run.failed", "session.completed"],
  "secret": "<signing secret — store it now, not shown again>"
}

GET /webhooks

{
  "items": [
    {
      "id": "wh_01H...",
      "url": "https://your-app.example.com/synthusers/webhook",
      "events": ["run.completed"],
      "last_delivery_at": "2026-05-15T18:00:00Z",
      "last_delivery_status": "200"
    }
  ]
}

The secret is not included after creation. If you lose it, delete the webhook and recreate it.

PATCH /webhooks/:id

Terminal window
curl -s -X PATCH "$API_URL/webhooks/wh_01H..." \
  -H "Authorization: Bearer $SYNTHUSERS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "events": ["run.completed"] }'

DELETE /webhooks/:id

Removes the webhook. Pending retries are dropped.

POST /webhooks/:id/test

Delivers a test event to your URL so you can iterate on your signature-verification code without starting a real run. The event’s event field is webhook.test — branch on it in your handler. The response tells you whether the delivery succeeded:

Terminal window
curl -s -X POST "$API_URL/webhooks/wh_01H.../test" \
  -H "Authorization: Bearer $SYNTHUSERS_API_KEY"
# → { "delivered": true, "status_code": 200, "attempt_count": 1 }

GET /webhooks/:id/deliveries

Returns the most recent delivery attempts for a webhook — useful when a delivery didn’t arrive. Each row includes the event, attempt count, status (pending, delivered, or dead), the last HTTP response code, and the next scheduled retry.