Sign in
Cloud Events

Generic signed webhook event

Receives arbitrary normalized webhook events, verified via X-Webhook-Signature HMAC over X-Webhook-Timestamp plus the raw body using WEBHOOK_SIGNING_SECRET. The Unix timestamp must be within five minutes of the server clock to prevent replay. The request names the owning userId; source defaults to webhook and may be mcp, github, linear, or stripe for connector/provider gateways. Payload is sealed, and routing uses the same cloud event router as provider webhooks.

post/v1/webhooks/events

Request

  • Base URL: / (relative, and the document was published on a file host, not at the API’s origin)
  • URL: /v1/webhooks/events
  • Auth: API key in header X-Webhook-Signature

Headers

X-Webhook-Timestampstring required

Unix timestamp included in the webhook signature; must be within five minutes of server time.

Request body

dedupeKeystring nullable

Optional idempotency anchor. If omitted, sourceEventId is required and derives <source>:<sourceAccountId>:<sourceEventId>.

eventTypestring nullable

Provider-specific event type.

occurredAtstring nullable

RFC3339 provider event time.

payloadobject

Full provider object. Sealed at rest; returned only by the event detail endpoint.

source'webhook' | 'mcp' | 'github' | 'linear' | 'stripe'

Webhook source.

sourceAccountIdstring nullable

External account or webhook integration key.

sourceEventIdstring nullable

Provider-side event id. Used to derive dedupeKey when dedupeKey is omitted.

subjectstring nullable

Short title used in UI and routing prompts. Defaults to eventType when omitted.

textstring nullable

Human-readable gist used in routing prompts. Defaults to a compact payload summary when omitted.

userIdstring required

Rowboat user id (UUID) owning the event.

Example request

{
  "dedupeKey": "webhook:zapier-acme-ar:evt_123",
  "eventType": "invoice.disputed",
  "occurredAt": "2026-06-06T14:00:00Z",
  "source": "webhook",
  "sourceAccountId": "zapier-acme-ar",
  "sourceEventId": "evt_123",
  "subject": "Invoice #4821 dispute",
  "text": "Acme disputed invoice #4821.",
  "userId": "a8dfa9b6-a7b2-46ea-982c-622a914c00e5"
}

Response

Duplicate dedupeKey: existing event returned.

dedupedboolean required

Whether this post matched an existing (user, source, dedupeKey) event.

eventIdstring required

Cloud event id.

matchedTaskCountinteger

Tasks the router matched (populated once routed).

routingStatus'pending' | 'routed' | 'skipped' | 'failed' required

Routing status at response time.

Example response

{
  "eventId": "0c0afab1-7f6f-4f0b-9d8e-1e58e8b0f111",
  "routingStatus": "pending"
}

Changes

No recorded changes to this operation across all 50 revisions of this API.