> For the complete documentation index, see [llms.txt](https://docs.welkinhealth.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.welkinhealth.com/designer/automations/inbox-message-status-webhook-events.md).

# Inbox Message Status Webhook Events

## Overview

Welkin automations can now trigger webhook actions when the delivery status of an outbound SMS or email message is updated by the carrier or email provider. This lets you notify external systems — billing platforms, CRMs, or monitoring tools — in real time when a message is delivered, failed, or encounters an error.

## Trigger Event Subtypes

Two new event subtypes are available when configuring an automation with an **Inbox Message** entity:

| Event subtype                        | Description                                                                                 |
| ------------------------------------ | ------------------------------------------------------------------------------------------- |
| `INBOX_SMS_STATUS_MESSAGE_UPDATED`   | Fires when the delivery status of an outbound SMS message changes (e.g., delivered, failed) |
| `INBOX_EMAIL_STATUS_MESSAGE_UPDATED` | Fires when the delivery status of an outbound email message changes                         |

To use these, create or edit an automation in Designer:

1. Set **Trigger Type** to **Event**
2. Set **Event Entity** to **Inbox Message**
3. Set **Event Subtype** to `INBOX_SMS_STATUS_MESSAGE_UPDATED` or `INBOX_EMAIL_STATUS_MESSAGE_UPDATED`
4. Add a **Webhook** action and select your configured webhook

## Webhook Payload Fields

When a webhook action fires in response to one of these events, the outbound payload automatically includes three additional predefined fields alongside the standard fields (`patientId`, `tenantName`, `instanceName`, `eventEntity`, `eventSubtype`, etc.):

| Field           | Type   | Description                                                                                                   |
| --------------- | ------ | ------------------------------------------------------------------------------------------------------------- |
| `messageId`     | UUID   | The unique identifier of the inbox message whose status changed                                               |
| `messageStatus` | string | The delivery status reported by the carrier or email provider (e.g., `DELIVERED`, `FAILED`)                   |
| `errorCode`     | string | The error code returned by the provider when delivery failed (e.g., `30007`). Omitted when delivery succeeded |

### Example payload (SMS failure)

```json
{
  "tenantName": "your-org",
  "instanceName": "main",
  "patientId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "eventEntity": "INBOX_MESSAGE",
  "eventSubtype": "INBOX_SMS_STATUS_MESSAGE_UPDATED",
  "sourceId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "sourceName": "SMS",
  "messageId": "1a2b3c4d-0000-0000-0000-000000000001",
  "messageStatus": "FAILED",
  "errorCode": "30007"
}
```

### Example payload (email delivery)

```json
{
  "tenantName": "your-org",
  "instanceName": "main",
  "patientId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "eventEntity": "INBOX_MESSAGE",
  "eventSubtype": "INBOX_EMAIL_STATUS_MESSAGE_UPDATED",
  "sourceId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "sourceName": "EMAIL",
  "messageId": "1a2b3c4d-0000-0000-0000-000000000002",
  "messageStatus": "DELIVERED"
}
```

## Custom Field Name Conflicts

If your webhook payload configuration includes a custom field whose name matches one of the predefined field names above (for example, a custom field named `messageStatus`), **the custom value takes precedence**. The predefined value is used only when no custom field with the same name is present.

## Related Topics

* [Automations](https://docs.welkinhealth.com/designer/automations/designer-how-to-create-automations) — creating and managing automations in Designer
* [Communication Center](https://docs.welkinhealth.com/care/communication/communication-center) — inbox and messaging in the Care Portal
* [Webhook Configuration](https://docs.welkinhealth.com/admin/apis-and-integrations/webhook-configuration) — setting up webhook endpoints in Admin


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.welkinhealth.com/designer/automations/inbox-message-status-webhook-events.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.