> ## Documentation Index
> Fetch the complete documentation index at: https://docs.novu.co/llms.txt
> Use this file to discover all available pages before exploring further.

# SMS Webhook SMS Integration with Novu

> Connect SMS Webhook to Novu to send SMS through your own HTTP API or custom SMS provider endpoint.

SMS Webhook lets you send SMS notifications through any HTTP API you control. Instead of a built-in provider SDK, Novu `POST`s each message to your **Base URL** with the subscriber phone number, message body, and sender ID.

Use this integration when your SMS gateway exposes a REST API that is not listed in Novu's provider catalog, or when you want Novu to call an internal service that handles delivery.

## Configure SMS Webhook in Novu

<Steps>
  <Step title="Prepare your SMS endpoint">
    Your endpoint must accept `POST` requests and return a JSON response. For local testing, use a tool like [webhook.site](https://webhook.site/).
  </Step>

  <Step title="Open the Integration Store">
    In the Novu dashboard, go to **Integrations Store** and click **Connect Provider**.
  </Step>

  <Step title="Select SMS Webhook">
    Under **SMS**, select **SMS Webhook** and click **Create Integration**.
  </Step>

  <Step title="Fill in integration fields">
    | Field                         | Required      | Description                                                            |
    | ----------------------------- | ------------- | ---------------------------------------------------------------------- |
    | **Base URL**                  | Yes           | The URL Novu calls to send each SMS.                                   |
    | **API Key Request Header**    | Yes           | Header name for your API key (for example, `X-API-KEY`).               |
    | **API Key**                   | Yes           | Value sent in that header.                                             |
    | **Secret Key Request Header** | No            | Optional second header name.                                           |
    | **Secret Key**                | No            | Value for the optional secret header.                                  |
    | **From**                      | Yes           | Default sender ID shown on outbound messages.                          |
    | **Id Path**                   | Yes           | Dot path to the message ID in your JSON response (default: `data.id`). |
    | **Date Path**                 | No            | Dot path to the sent date in your response (default: `data.date`).     |
    | **Authenticate by token**     | No            | Fetch a token from an auth URL before each send.                       |
    | **Auth URL**                  | If token auth | URL Novu calls to obtain the token.                                    |
    | **Authentication Token Key**  | If token auth | Response field and header name for the token.                          |
  </Step>

  <Step title="Activate the integration">
    Mark the integration as **Active** and save.
  </Step>
</Steps>

## Request format

For each SMS, Novu sends a `POST` request to your **Base URL** with the configured API key headers.

```json theme={null}
{
  "to": "+1234567890",
  "content": "Your verification code is 123456",
  "sender": "MyApp"
}
```

| Field     | Description                                                             |
| --------- | ----------------------------------------------------------------------- |
| `to`      | Recipient phone number from the subscriber profile or trigger override. |
| `content` | Rendered SMS body from the workflow step.                               |
| `sender`  | Sender ID from the integration **From** field or trigger override.      |

## Response format

Return a `2xx` JSON response. Novu reads the message ID and date using the **Id Path** and **Date Path** you configured.

Example response when **Id Path** is `message.id` and **Date Path** is `message.date`:

```json theme={null}
{
  "message": {
    "id": "msg_abc123",
    "date": "2026-01-14T10:30:00.000Z"
  }
}
```

If the date field is missing, Novu uses the current timestamp.

## Token authentication (optional)

When **Authenticate by token** is enabled:

1. Novu `POST`s to your **Auth URL** with the API key headers.
2. Novu reads the token from `data.<Authentication Token Key>` in the response.
3. Novu sends the SMS request to **Base URL** with that token in a header named after **Authentication Token Key**.

## Customize the request body

Use [provider overrides](/platform/integrations/trigger-overrides#provider-overrides) to merge extra fields into the outbound request:

```typescript theme={null}
import { Novu } from '@novu/api';

const novu = new Novu({ secretKey: '<YOUR_SECRET_KEY_HERE>' });

await novu.trigger({
  workflowId: 'workflow-id',
  to: { subscriberId: 'user-123' },
  overrides: {
    providers: {
      'generic-sms': {
        _passthrough: {
          body: {
            templateId: 'otp-template',
          },
        },
      },
    },
  },
});
```

The `_passthrough.body` fields are deep-merged into the default payload. See [SMS overrides](/platform/integrations/sms#override-sms-settings) to change `to`, `from`, or `content` at trigger time.

<Note>
  On Novu Cloud, **Base URL** and **Auth URL** must be publicly reachable HTTPS endpoints. Private or internal URLs are blocked by SSRF protection.
</Note>