Soryxa Webhooks and Connectors

Inbound webhook path

Inbound connector webhooks use the integration slug and team public UUID. Generic webhook-compatible connectors accept a top-level email or email_address and optional metadata. Signed connectors are verified before work is queued.

POST /api/v1/integrations/webhook/{teamPublicUuid}/{slug}
Content-Type: application/json

{
  "email": "user@example.com",
  "metadata": {
    "workflow": "signup"
  }
}

Provider-specific handlers may support other payload shapes. Use the setup guide for the connector configured in your Soryxa workspace.

For n8n inbound requests, include a non-empty top-level delivery_id of at most 255 characters and a timestamp within five minutes of server time. Send X-Soryxa-Signature as the lowercase hexadecimal HMAC-SHA256 of the exact raw JSON body using the connector signing secret, without a sha256= prefix. Keep the delivery_id stable when retrying the same event. A first accepted request returns 202 validation_accepted; an accepted replay returns 200 validation_already_accepted without queuing or charging a second validation. Replays must still pass signature and timestamp checks.

Outbound event shape

This example shows the custom-webhook and n8n envelope. Use event and source to route each payload. Inbound validate actions require an active outbound or bidirectional connector with read_results, a configured webhook URL, and a subscription to validation.completed or validation.failed. Otherwise the request returns 422 no_result_webhooks_configured.

{
  "delivery_id": "e6c47f48-6d7c-4f3b-b35f-49e508beeb53",
  "event": "validation.completed",
  "source": "soryxa",
  "occurred_at": "2026-09-06T12:00:00+00:00",
  "timestamp": "2026-09-06T12:00:00+00:00",
  "data": {
    "email": "user@example.com",
    "decision": "allow",
    "reason_code": "CLASSIFICATION_VALID",
    "score": 96
  }
}