---
updatedAt: 2026-10-26T14:01:34.000Z
---

# FAILED notification for an outbound message

Sent when a message you sent failed to be delivered by the channel. `eventType` is `NOTIFICATION` and `notificationType` is `FAILED`.

The callback carries the `FAILED` status and the correlating `outboundId` so you can identify which message could not be delivered. This is distinct from `outboundFailureNotification`, which fires when Enrich could not submit the message to the channel at all.

# OpenAPI definition

```json
{
  "openapi": "3.1.0",
  "info": {
    "title": "First Orion Enrich Branded Messaging API",
    "version": "2026-09-01.0.rc-0",
    "description": "# First Orion Enrich Branded Messaging\n\nThis document describes the complete Enrich Branded Messaging integration surface:\n\n- **`paths`** — the REST endpoints **you call** on First Orion: queueing outbound RCS messages, and fetching the JWKS used to verify callbacks.\n- **`webhooks`** — the callbacks **Enrich calls on you**. You implement an HTTPS endpoint and register it against an RCS agent; Enrich `POST`s every inbound message, notification, and outbound send failure to that URL.\n\n## Event catalog\n\nEnrich sends two families of payloads to your webhook:\n\n1. **`EndUserWebhookPayload`** — every inbound message and notification. `eventType` is either `MESSAGE` or `NOTIFICATION`.\n   - `MESSAGE` events carry a `messageContent` object whose shape is selected by `messageContent.messageType` (`TEXT`, `MEDIA`, `CHOICE`, `LOCATION`).\n   - `NOTIFICATION` events carry a `notificationType` (`TYPING`, `DELIVERED`, `READ`, `FAILED`, `CHANNEL_SWITCHED`).\n2. **`OutboundFailureWebhookPayload`** — Enrich failed to send an outbound message you requested. Flatter shape, no `eventType` field.\n\nAll callbacks are delivered to the **same** webhook URL. They are listed separately here to document every distinct payload variant your endpoint must handle.\n\n## Channels\n\nEnd users may respond over RCS or SMS. Both are delivered to your webhook using the same payloads — **there is no channel field**, so an SMS reply and an RCS reply are structurally identical.\n\n- **SMS** replies arrive only as `MESSAGE` events with `messageContent.messageType` = `TEXT`. Delivery outcomes for messages you send over SMS may also arrive as `DELIVERED` / `FAILED` notifications.\n- **RCS** supports the full set of events. The richer variants — `MEDIA`, `CHOICE` and `LOCATION` messages, and the `TYPING` and `READ` notifications — are only produced for RCS conversations.\n\nDesign your handler to treat `TEXT` messages and delivery notifications as channel-agnostic, and to simply not expect the RCS-only variants for SMS conversations.\n\n## Callback delivery mechanics\n\n- **Method / content type:** `POST` with `Content-Type: application/json`.\n- **Endpoint:** the webhook URL you configured for the agent.\n- **Expected response:** return a `2xx` status code to acknowledge receipt.\n  - A `4xx` response is treated as permanent — Enrich will **not** retry.\n  - A `5xx` response (or a network/connection error) is retried up to **4 attempts** with a **5 second** delay between attempts. After retries are exhausted the event is dropped.\n- **Ordering:** events are processed per contact, but delivery ordering is not guaranteed across event types.\n\n## Callback authentication\n\nEvery callback carries an `Authorization: Bearer <JWT>` header — a `PS256`-signed token produced by First Orion (KMS-backed asymmetric signing). See the `enrichCallbackJwt` security scheme for the claim set, and `GET /.well-known/jwks.json` for the verification keys.\n\n## Schema naming\n\n- **Outbound** (things you send) content types are named `*Content`: `TextContent`, `MediaContent`, `CardContent`, `CarouselContent`, `ChoiceContent`.\n- **Inbound** (things you receive) content types are grouped under `InboundMessageContent`: `TextMessageContent`, `MediaMessageContent`, `ChoiceResponseContent`, `LocationMessageContent`.\n",
    "contact": {
      "name": "First Orion Enrich",
      "url": "https://firstorion.com"
    }
  },
  "servers": [
    {
      "url": "https://api.firstorion.com",
      "description": "Production. Applies to the endpoints under `paths` only — callbacks under `webhooks` are delivered to the URL you configure for your agent."
    }
  ],
  "tags": [
    {
      "name": "Callbacks",
      "description": "Payloads Enrich POSTs to the webhook URL you host. You implement these; Enrich is the client."
    }
  ],
  "webhooks": {
    "failedNotification": {
      "post": {
        "tags": [
          "Callbacks"
        ],
        "operationId": "failedNotification",
        "summary": "FAILED notification for an outbound message",
        "description": "Sent when a message you sent failed to be delivered by the channel. `eventType` is `NOTIFICATION` and `notificationType` is `FAILED`.\n\nThe callback carries the `FAILED` status and the correlating `outboundId` so you can identify which message could not be delivered. This is distinct from `outboundFailureNotification`, which fires when Enrich could not submit the message to the channel at all.",
        "security": [
          {
            "enrichCallbackJwt": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/EndUserWebhookPayload"
              },
              "examples": {
                "failed": {
                  "summary": "Delivery failure",
                  "value": {
                    "agentId": "abc123xyz456",
                    "agentDisplayName": "Acme Support",
                    "contactNumber": "+12345678901",
                    "eventType": "NOTIFICATION",
                    "messageContent": null,
                    "notificationType": "FAILED",
                    "outboundId": "9f1c2a5e-4b0d-4e2a-9a1b-1234567890ab",
                    "isOptOut": false,
                    "correlateId": "correlation-id-1"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Callback acknowledged."
          },
          "4XX": {
            "description": "Permanent failure. Enrich will not retry."
          },
          "5XX": {
            "description": "Transient failure. Enrich retries up to 4 times, 5s apart."
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "enrichCallbackJwt": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT",
        "description": "A per-request `PS256`-signed JWT issued by First Orion (KMS-backed), sent on every callback in the `Authorization: Bearer <token>` header. Verify it against `GET /.well-known/jwks.json`.\n\nClaims:\n- `iss` = `firstorion.com`\n- `aud` = your configured webhook URL\n- `sub` = `First Orion Enrich Branded Messaging Webhook`\n- `jti` = unique id per delivery\n- `iat` / `exp` = issued-at and expiry (5 minute lifetime)\n- `pbh` = `base64url(SHA-256(rawRequestBody))`, binding the token to the exact request body. Verify this to detect body tampering."
      }
    },
    "schemas": {
      "ConversationMetadata": {
        "type": "object",
        "description": "Arbitrary JSON metadata attached to the conversation. Set on an outbound send, persisted on the conversation, and echoed back on inbound callbacks. Sticky: omitting it on a later send does not clear it. Max 2048 characters serialized.",
        "additionalProperties": true,
        "example": {
          "campaign": "summer-2025",
          "source": "crm"
        }
      },
      "EndUserResponseType": {
        "type": "string",
        "description": "Discriminates whether the callback payload is an inbound message or a notification.",
        "enum": [
          "MESSAGE",
          "NOTIFICATION"
        ]
      },
      "EndUserNotificationType": {
        "type": "string",
        "description": "The kind of notification. Present (non-null) only when `eventType` is `NOTIFICATION`.",
        "enum": [
          "READ",
          "TYPING",
          "DELIVERED",
          "FAILED",
          "CHANNEL_SWITCHED"
        ]
      },
      "InboundMessageContent": {
        "description": "Polymorphic inbound message content. The concrete shape is selected by the `messageType` discriminator. Present (non-null) only when `eventType` is `MESSAGE`.",
        "oneOf": [
          {
            "$ref": "#/components/schemas/TextMessageContent"
          },
          {
            "$ref": "#/components/schemas/MediaMessageContent"
          },
          {
            "$ref": "#/components/schemas/ChoiceResponseContent"
          },
          {
            "$ref": "#/components/schemas/LocationMessageContent"
          }
        ],
        "discriminator": {
          "propertyName": "messageType",
          "mapping": {
            "TEXT": "#/components/schemas/TextMessageContent",
            "MEDIA": "#/components/schemas/MediaMessageContent",
            "CHOICE": "#/components/schemas/ChoiceResponseContent",
            "LOCATION": "#/components/schemas/LocationMessageContent"
          }
        }
      },
      "TextMessageContent": {
        "type": "object",
        "description": "Content for an inbound TEXT message.",
        "required": [
          "messageType",
          "text"
        ],
        "properties": {
          "messageType": {
            "const": "TEXT",
            "description": "Always `TEXT`."
          },
          "text": {
            "type": "string",
            "description": "The text the end user sent.",
            "example": "Hi! I need help with my order."
          }
        }
      },
      "MediaMessageContent": {
        "type": "object",
        "description": "Content for an inbound MEDIA message.",
        "required": [
          "messageType",
          "url"
        ],
        "properties": {
          "messageType": {
            "const": "MEDIA",
            "description": "Always `MEDIA`."
          },
          "url": {
            "type": "string",
            "format": "uri",
            "description": "Link to the hosted media file.",
            "example": "https://media.example.com/rcs/inbound/abc123.jpg"
          }
        }
      },
      "ChoiceResponseContent": {
        "type": "object",
        "description": "Content for an inbound CHOICE (suggested reply / action) response.",
        "required": [
          "messageType",
          "originalMessageId",
          "postbackData"
        ],
        "properties": {
          "messageType": {
            "const": "CHOICE",
            "description": "Always `CHOICE`."
          },
          "originalMessageId": {
            "type": "string",
            "description": "Message id of the RCS message that presented the choice.",
            "example": "01EQBC1A3BEK731GY4YXEN0C2R"
          },
          "postbackData": {
            "type": "string",
            "description": "Postback payload attached to the selected suggestion.",
            "example": "track_my_order"
          }
        }
      },
      "LocationMessageContent": {
        "type": "object",
        "description": "Content for an inbound LOCATION message.",
        "required": [
          "messageType",
          "title",
          "latitude",
          "longitude"
        ],
        "properties": {
          "messageType": {
            "const": "LOCATION",
            "description": "Always `LOCATION`."
          },
          "title": {
            "type": "string",
            "description": "Human-readable label for the shared location.",
            "example": "Acme Warehouse"
          },
          "latitude": {
            "type": "number",
            "format": "double",
            "example": 34.746483
          },
          "longitude": {
            "type": "number",
            "format": "double",
            "example": -92.289597
          }
        }
      },
      "EndUserWebhookPayload": {
        "type": "object",
        "description": "The envelope for all inbound message and notification callbacks.\n\n- When `eventType` is `MESSAGE`, `messageContent` is populated and `notificationType` is `null`.\n- When `eventType` is `NOTIFICATION`, `notificationType` is populated and `messageContent` is `null`.",
        "required": [
          "agentId",
          "agentDisplayName",
          "contactNumber",
          "eventType",
          "isOptOut"
        ],
        "properties": {
          "agentId": {
            "type": "string",
            "description": "The RCS agent id the event is associated with.",
            "example": "abc123xyz456"
          },
          "agentDisplayName": {
            "type": "string",
            "description": "The display name of the RCS agent.",
            "example": "Acme Support"
          },
          "contactNumber": {
            "type": "string",
            "description": "The end user's phone number in E.164 format. This is the raw, unhashed number.",
            "example": "+12345678901"
          },
          "eventType": {
            "$ref": "#/components/schemas/EndUserResponseType"
          },
          "messageContent": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/InboundMessageContent"
              },
              {
                "type": "null"
              }
            ],
            "description": "The inbound message content. Present only for `MESSAGE` events; `null` for `NOTIFICATION` events."
          },
          "notificationType": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/EndUserNotificationType"
              },
              {
                "type": "null"
              }
            ],
            "description": "The notification kind. Present only for `NOTIFICATION` events; `null` for `MESSAGE` events."
          },
          "outboundId": {
            "type": [
              "string",
              "null"
            ],
            "description": "Correlates the event back to the originating outbound message (extracted from the outbound message metadata). `null` when not applicable, such as unsolicited inbound messages.",
            "example": "9f1c2a5e-4b0d-4e2a-9a1b-1234567890ab"
          },
          "isOptOut": {
            "type": "boolean",
            "default": false,
            "description": "`true` when an inbound TEXT message matched an opt-out keyword (e.g. `STOP`, `UNSUBSCRIBE`, `CANCEL`). Always `false` for notifications and non-opt-out messages."
          },
          "correlateId": {
            "type": [
              "string",
              "null"
            ],
            "description": "The `correlateId` value supplied on the originating send request, if any. `null` when not provided.",
            "example": "correlation-id-1"
          },
          "conversationMetadata": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/ConversationMetadata"
              },
              {
                "type": "null"
              }
            ],
            "description": "Metadata echoed from the conversation when present. Omitted from the payload entirely when there is none.",
            "example": {
              "orderId": "ORD-5589"
            }
          }
        }
      }
    }
  },
  "x-readme": {
    "explorer-enabled": false
  }
}
```