> For the complete documentation index, see [llms.txt](https://flapjax.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://flapjax.gitbook.io/docs/rest-api/reference/webhook-callbacks/messagechief-callback.md).

# MessageChief Callback

## MessageChief delivery-status webhook

> Receives delivery-status events from MessageChief when an SMS message reaches a final status. This endpoint is called by MessageChief — not by API consumers — and requires no authentication.\
> \
> The payload carries only MessageChief's \`payload.message\_id\`; the affected organization and person are resolved by matching it against the provider message ID stamped on the outbound message at send time. Callbacks that don't match any known message are acknowledged with \*\*200\*\* and no action is taken.\
> \
> Only \`message\_finalized\` events advance message status. \`channel\_message\_finalized\` (and any unrecognized event type) is acknowledged with \*\*200\*\* without action. Within \`message\_finalized\`, the \`payload.status\` values map to status updates as follows: \`delivered\` → SMS delivered, \`failed\` → SMS failed, \`rejected\` → SMS undelivered.\
> \
> {% hint style="info" %}\
> A \*\*500\*\* response signals MessageChief to retry the webhook — it is returned when the correlation lookup or the status-update dispatch fails, so status updates are never silently dropped.\
> {% endhint %}<br>

```json
{"openapi":"3.0.3","info":{"title":"Listener API","version":"1.0.0"},"tags":[{"name":"messagechief-callback"}],"servers":[{"url":"https://{domain}/v1","variables":{"domain":{"default":"your-domain","description":"Your deployment domain"}}}],"security":[],"paths":{"/messagechief":{"post":{"summary":"MessageChief delivery-status webhook","operationId":"messageChiefCallback","tags":["messagechief-callback"],"description":"Receives delivery-status events from MessageChief when an SMS message reaches a final status. This endpoint is called by MessageChief — not by API consumers — and requires no authentication.\n\nThe payload carries only MessageChief's `payload.message_id`; the affected organization and person are resolved by matching it against the provider message ID stamped on the outbound message at send time. Callbacks that don't match any known message are acknowledged with **200** and no action is taken.\n\nOnly `message_finalized` events advance message status. `channel_message_finalized` (and any unrecognized event type) is acknowledged with **200** without action. Within `message_finalized`, the `payload.status` values map to status updates as follows: `delivered` → SMS delivered, `failed` → SMS failed, `rejected` → SMS undelivered.\n\n{% hint style=\"info\" %}\nA **500** response signals MessageChief to retry the webhook — it is returned when the correlation lookup or the status-update dispatch fails, so status updates are never silently dropped.\n{% endhint %}\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MessageChiefEvent"}}}},"responses":{"200":{"description":"Event acknowledged. Returned when the status update was processed, when the event type requires no action, or when the callback could not be correlated to a known message.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessResponse"}}}},"400":{"description":"Invalid request body or missing required payload fields.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Correlation lookup or status-update dispatch failed. MessageChief will retry the webhook.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"components":{"schemas":{"MessageChiefEvent":{"type":"object","description":"Webhook event sent by MessageChief when a message reaches a final status.\n","required":["event","payload"],"properties":{"event":{"type":"string","description":"Event type. Only `message_finalized` triggers a status update; other event types are acknowledged without action.\n","enum":["message_finalized","channel_message_finalized"]},"payload":{"$ref":"#/components/schemas/MessageChiefEventPayload"}}},"MessageChiefEventPayload":{"type":"object","description":"Payload of a MessageChief webhook event.","required":["message_id","status"],"properties":{"message_id":{"type":"string","description":"MessageChief's public message ID. Used to correlate the callback to the outbound message it refers to.\n"},"channel_id":{"type":"string","description":"Channel message public ID (present on `channel_message_finalized` events only).\n"},"status":{"type":"string","description":"Final message status. `delivered`, `failed`, and `rejected` are message-level statuses; `expired` and `canceled` are channel-level statuses sent only on `channel_message_finalized` events.\n","enum":["delivered","failed","rejected","expired","canceled"]},"finalized_at":{"type":"string","format":"date-time","description":"ISO-8601 timestamp of when the message was finalized."}}},"SuccessResponse":{"type":"object","description":"Standard success response envelope.","properties":{"status":{"type":"string","enum":["Success"]},"data":{"type":"boolean"}}},"ErrorResponse":{"type":"object","description":"Standard error response envelope.","properties":{"error":{"type":"string","description":"Machine-readable error type. Use this for programmatic error handling.\n","enum":["operation_failed","failed_binding_json","invalid_json","invalid_parameter","not_found","duplicate_entry","rate_limit_exceeded"]},"errorstack":{"type":"object","nullable":true,"description":"Detailed error stack (only present for server errors)."}}}}}}
```