Webhook event catalog

Samva delivers webhook events to the endpoints you register. This page catalogs the events the platform emits, the type string each carries, when it fires, and the payload fields it delivers. To register an endpoint and verify signatures, see Receive webhooks.

Envelope

Every delivery is a POST with a JSON body in a fixed envelope. The event field is the event type string; messageId is the message the event is about; timestamp is the delivery time in ISO 8601; and data carries the event-specific fields.

{
  "event": "message.delivered",
  "messageId": "3f2a9c1e-7b4d-4e8a-9c2f-1a2b3c4d5e6f",
  "timestamp": "2026-01-15T09:42:11.204Z",
  "data": {
    "channel": "email",
    "status": "delivered",
    "providerMessageId": "0100018f2a...-000000"
  }
}

Each request also carries the X-Webhook-Event (event type), X-Webhook-Id (endpoint id), and X-Webhook-Signature headers. Verify the signature before you trust the body, as described in Receive webhooks.

The data object is populated on a best-effort basis: a field is present only when the underlying provider event supplied it. Treat every field inside data as optional and code defensively.

Message events

Message events track a single message through its send and delivery lifecycle. Every message event carries the message's channel and a status string inside data, plus channel- and provider-specific fields.

message.sent

Fires when a provider accepts the message for delivery. This is the handoff to the upstream mail or messaging provider, not confirmation that the recipient received it.

{
  "event": "message.sent",
  "messageId": "3f2a9c1e-7b4d-4e8a-9c2f-1a2b3c4d5e6f",
  "timestamp": "2026-01-15T09:42:10.031Z",
  "data": {
    "channel": "sms",
    "status": "sent",
    "providerMessageId": "SM7c1e...",
    "to": "+14155550101",
    "from": "+14155550100",
    "segments": 1,
    "cost": 0.0079
  }
}

message.delivered

Fires when the recipient's provider confirms delivery. For email, this is the recipient's mail server accepting the message; for SMS, a carrier delivery receipt.

{
  "event": "message.delivered",
  "messageId": "3f2a9c1e-7b4d-4e8a-9c2f-1a2b3c4d5e6f",
  "timestamp": "2026-01-15T09:42:14.882Z",
  "data": {
    "channel": "email",
    "status": "delivered",
    "providerMessageId": "0100018f2a...-000000",
    "subject": "Welcome to Samva",
    "toEmails": ["ada@example.com"]
  }
}

message.failed

Fires when a message cannot be delivered. The failure may originate from the provider, from a suppressed recipient, or from an error while processing the send. failureReason is a human-readable explanation; errorCode is a machine-readable code when the source provides one.

{
  "event": "message.failed",
  "messageId": "3f2a9c1e-7b4d-4e8a-9c2f-1a2b3c4d5e6f",
  "timestamp": "2026-01-15T09:42:12.507Z",
  "data": {
    "channel": "email",
    "status": "failed",
    "failureReason": "Permanent",
    "errorCode": "General"
  }
}

message.bounced

Fires for email when the recipient's mail server rejects the message after acceptance, or when a recipient marks it as spam. failureReason carries the bounce or complaint type.

{
  "event": "message.bounced",
  "messageId": "3f2a9c1e-7b4d-4e8a-9c2f-1a2b3c4d5e6f",
  "timestamp": "2026-01-15T09:43:01.117Z",
  "data": {
    "channel": "email",
    "status": "bounced",
    "providerMessageId": "0100018f2a...-000000",
    "failureReason": "Permanent",
    "errorCode": "General",
    "subject": "Welcome to Samva",
    "toEmails": ["ada@example.com"]
  }
}

message.received

Fires when Samva receives an inbound message and routing matches one of your endpoints. Inbound email and inbound SMS both emit this event; the direction field is inbound.

{
  "event": "message.received",
  "messageId": "a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
  "timestamp": "2026-01-15T10:05:33.900Z",
  "data": {
    "channel": "email",
    "direction": "inbound",
    "from": "ada@example.com",
    "to": "support@your-domain.com",
    "subject": "Re: Welcome to Samva",
    "conversationId": "c9d8e7f6-1234-5678-9abc-def012345678",
    "hasAttachments": false,
    "isAutoReply": false
  }
}

Subscribing to events

You subscribe an endpoint to events with the events array when you create or update it. Pass the type strings above, for example ["message.delivered", "message.failed"]. Subscribe only to the events your application acts on; you can register multiple endpoints to route different events to different services. See Receive webhooks for the full registration and verification flow.

Next steps