Skip to main content

Webhook Dispatcher — Event Schemas

Status: populated Owner: Platform Engineering Last updated: 2026-04-18 Companion: API_CONTRACTS · APPLICATION_LOGIC

1. Inbound: webhook.dispatch​

{
  "$schema": "https://schemas.ghasi.io/sms-gateway/webhook.dispatch/v1.json",
  "type": "object",
  "required": ["eventId", "accountId", "messageId", "dlrStatus", "to", "operatorId", "occurredAt"],
  "properties": {
    "eventId":      { "type": "string", "format": "uuid" },
    "schemaVersion":{ "type": "string", "const": "1.0" },
    "accountId":    { "type": "string", "format": "uuid" },
    "messageId":    { "type": "string", "format": "uuid" },
    "dlrStatus":    { "type": "string", "enum": ["DELIVERED","FAILED","UNDELIVERED","EXPIRED","REJECTED","UNKNOWN"] },
    "to":           { "type": "string", "pattern": "^\\+[1-9]\\d{1,14}$" },
    "operatorId":   { "type": "string", "format": "uuid" },
    "occurredAt":   { "type": "string", "format": "date-time" },
    "metadata":     { "type": "object", "additionalProperties": { "type": "string" } }
  }
}

Example​

{
  "eventId": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
  "schemaVersion": "1.0",
  "accountId": "d4e5f6a7-b8c9-0123-def0-234567890123",
  "messageId": "c3d4e5f6-a7b8-9012-cdef-123456789012",
  "dlrStatus": "DELIVERED",
  "to": "+441234567890",
  "operatorId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "occurredAt": "2026-04-18T10:23:46Z"
}

2. DlrStatus → WebhookEventType Mapping​

dlrStatusX-Ghasi-Event / WebhookEventType
DELIVEREDDLR_DELIVERED
FAILEDDLR_FAILED
UNDELIVEREDDLR_UNDELIVERED
EXPIREDDLR_EXPIRED
REJECTEDDLR_REJECTED
UNKNOWNDLR_UNKNOWN

3. Outbound HTTP Webhook Payload​

{
  "$schema": "https://schemas.ghasi.io/sms-gateway/webhook-payload/v1.json",
  "type": "object",
  "required": ["id", "event", "timestamp", "data"],
  "properties": {
    "id":        { "type": "string", "format": "uuid", "description": "deliveryId — stable across retries" },
    "event":     { "type": "string", "enum": ["DLR_DELIVERED","DLR_FAILED","DLR_UNDELIVERED","DLR_EXPIRED","DLR_REJECTED","DLR_UNKNOWN"] },
    "timestamp": { "type": "integer", "description": "Unix epoch seconds" },
    "data": {
      "type": "object",
      "required": ["messageId", "accountId", "dlrStatus", "to", "operatorId", "occurredAt"],
      "properties": {
        "messageId":  { "type": "string", "format": "uuid" },
        "accountId":  { "type": "string", "format": "uuid" },
        "dlrStatus":  { "type": "string" },
        "to":         { "type": "string" },
        "operatorId": { "type": "string", "format": "uuid" },
        "occurredAt": { "type": "string", "format": "date-time" }
      }
    }
  }
}

Example Webhook Payload​

{
  "id": "e5f6a7b8-c9d0-1234-ef01-234567890123",
  "event": "DLR_DELIVERED",
  "timestamp": 1713434626,
  "data": {
    "messageId": "c3d4e5f6-a7b8-9012-cdef-123456789012",
    "accountId": "d4e5f6a7-b8c9-0123-def0-234567890123",
    "dlrStatus": "DELIVERED",
    "to": "+441234567890",
    "operatorId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "occurredAt": "2026-04-18T10:23:46Z"
  }
}

4. Outbound NATS: webhook.dispatch.deadletter​

{
  "$schema": "https://schemas.ghasi.io/sms-gateway/webhook.dispatch.deadletter/v1.json",
  "type": "object",
  "required": ["eventId", "deliveryId", "webhookId", "accountId", "reason", "attemptCount", "occurredAt"],
  "properties": {
    "eventId":       { "type": "string", "format": "uuid" },
    "schemaVersion": { "type": "string", "const": "1.0" },
    "deliveryId":    { "type": "string", "format": "uuid" },
    "webhookId":     { "type": "string", "format": "uuid" },
    "accountId":     { "type": "string", "format": "uuid" },
    "reason":        { "type": "string", "const": "MAX_RETRIES_EXCEEDED" },
    "attemptCount":  { "type": "integer", "const": 5 },
    "lastHttpStatus":{ "type": "integer" },
    "lastError":     { "type": "string" },
    "occurredAt":    { "type": "string", "format": "date-time" }
  }
}