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

# SMS Webhook SMS Integration with WorldVisa

> Connect an SMS webhook provider to WorldVisa to send SMS through your own HTTP API or a custom SMS provider endpoint using a webhook URL, headers, and JSON payload.

SMS Webhook lets you send SMS notifications through any HTTP API you control. Instead of a built-in provider SDK, WorldVisa `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 WorldVisa's provider catalog, or when you want WorldVisa to call an internal service that handles delivery.

## Configure SMS Webhook in WorldVisa

**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](https://webhook.site/).

**2. Open the Integration Store**

In the WorldVisa 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**

| Field | Required | Description |
| - | - | - |
| **Base URL** | Yes | The URL WorldVisa 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 WorldVisa calls to obtain the token. |
| **Authentication Token Key** | If token auth | Response field and header name for the token. |

**5. Activate the integration**

Mark the integration as **Active** and save.

## Request format

For each SMS, WorldVisa 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. WorldVisa 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, WorldVisa uses the current timestamp.

## Token authentication (optional)

When **Authenticate by token** is enabled:

1. WorldVisa `POST`s to your **Auth URL** with the API key headers.
2. WorldVisa reads the token from `data.<Authentication Token Key>` in the response.
3. WorldVisa 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](https://docs.worldvisagroup.com/developers/integrations/trigger-overrides.md#provider-overrides) to merge extra fields into the outbound request:

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


## Related topics

- [SMS](https://docs.worldvisagroup.com/developers/integrations/sms.md)
- [Sendchamp SMS Integration with WorldVisa](https://docs.worldvisagroup.com/developers/integrations/sms/sendchamp.md)
- [Azure SMS SMS Integration with WorldVisa](https://docs.worldvisagroup.com/developers/integrations/sms/azure.md)
- [SMS Central SMS Integration with WorldVisa](https://docs.worldvisagroup.com/developers/integrations/sms/sms-central.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.