Skip to main content
SMS Webhook lets you send SMS notifications through any HTTP API you control. Instead of a built-in provider SDK, Novu POSTs 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

1

Prepare your SMS endpoint

Your endpoint must accept POST requests and return a JSON response. For local testing, use a tool like webhook.site.
2

Open the Integration Store

In the Novu dashboard, go to Integrations Store and click Connect Provider.
3

Select SMS Webhook

Under SMS, select SMS Webhook and click Create Integration.
4

Fill in integration fields

FieldRequiredDescription
Base URLYesThe URL Novu calls to send each SMS.
API Key Request HeaderYesHeader name for your API key (for example, X-API-KEY).
API KeyYesValue sent in that header.
Secret Key Request HeaderNoOptional second header name.
Secret KeyNoValue for the optional secret header.
FromYesDefault sender ID shown on outbound messages.
Id PathYesDot path to the message ID in your JSON response (default: data.id).
Date PathNoDot path to the sent date in your response (default: data.date).
Authenticate by tokenNoFetch a token from an auth URL before each send.
Auth URLIf token authURL Novu calls to obtain the token.
Authentication Token KeyIf token authResponse field and header name for the token.
5

Activate the integration

Mark the integration as Active and save.

​
Request format

For each SMS, Novu sends a POST request to your Base URL with the configured API key headers. 
{
  "to": "+1234567890",
  "content": "Your verification code is 123456",
  "sender": "MyApp"
}
FieldDescription
toRecipient phone number from the subscriber profile or trigger override.
contentRendered SMS body from the workflow step.
senderSender 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: 
{
  "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 POSTs 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 to merge extra fields into the outbound request: 
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 to change to, from, or content at trigger time.
On Novu Cloud, Base URL and Auth URL must be publicly reachable HTTPS endpoints. Private or internal URLs are blocked by SSRF protection.