> For the complete documentation index, see [llms.txt](https://docs.webtonative.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.webtonative.com/javascript-apis/webtonative-notifications/webhook-connectors/custom-connector.md).

# Custom Connector

Send automatic push notifications to your app users from any platform or backend: your own server, Laravel, Node.js, Magento, or anything that can send an HTTP request.

You send JSON to a connector's webhook URL with its secret in the `x-webtonative-secret` header, and WebToNative turns it into a push notification for the right user.

> You'll need to import the javascript file in your website before starting from this [link](https://docs.webtonative.com/javascript-apis/getting-started).

> **Platform support:** Android and iOS.

> **Before you start:**
>
> * Your plan must include **WebToNative Push**.
> * Push must be configured for your app (Android and/or iOS) in the WebToNative dashboard.

***

## How it works

1. **Link users to devices.** Your website calls `WTN.Notification.setExternalUserId()` with your user's ID when they log in, and `removeExternalUserId()` when they log out.
2. **Your backend sends a webhook.** When the event happens, your server sends JSON to the connector's webhook URL, with the Secret Code in the `x-webtonative-secret` header.
3. **WebToNative sends the notification.** We read the user ID from the payload, using the path you set when creating the connector, and send your notification to every device linked to that user.

***

## 1. Link your users to their devices

Link each logged-in user to their device from your website, using the WebToNative Notification functions. Follow the steps on the [Webtonative Notifications](https://docs.webtonative.com/javascript-apis/webtonative-notifications) page:

1. **On login:** call [`setExternalUserId`](https://docs.webtonative.com/javascript-apis/webtonative-notifications#set-external-user-id) with your user's ID after they sign in, and on page load while they're signed in.

   ```javascript
   window.WTN.Notification.setExternalUserId("u123");
   ```
2. **On logout:** call [`removeExternalUserId`](https://docs.webtonative.com/javascript-apis/webtonative-notifications#remove-external-user-id). It only unlinks the user from the device. It doesn't log the user out or refresh the page, so handle your own logout and redirect as usual.

   ```javascript
   window.WTN.Notification.removeExternalUserId();
   ```

The [Webtonative Notifications](https://docs.webtonative.com/javascript-apis/webtonative-notifications) page has the full examples (Plain Javascript and npm), the responses, and the errors for both functions.

> **Use the same ID everywhere.** The ID you pass to `setExternalUserId` must be the same value you send in your webhook payload. Pass it as a string, e.g. `"42"`.

***

## 2. Create the connector in WebToNative

### Step 1: Open Webhook Connector

1. Log in to the WebToNative dashboard.
2. Go to **My Apps** and select your app.
3. In the sidebar, open **Push Notification > Webhook Connector**.

<figure><img src="https://46162361-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MbRbEDU7JrvMAgg52AY%2Fuploads%2FShRmDDM4hA5E7kp8t3nA%2Fwebhook-connector-page.png?alt=media&amp;token=ba1c8d81-a2d2-4f21-839c-ff7105e1a398" alt=""><figcaption></figcaption></figure>

### Step 2: Add Connector (Step 1 of 2)

1. Click **+ Connect Webhook** (or **+ Add Connector** if you already have connectors).
2. Select **Custom** and click **Continue**.

<figure><img src="https://46162361-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MbRbEDU7JrvMAgg52AY%2Fuploads%2Fi4HZ6zxgax6ROUGaVjZU%2Fimage%20(1).png?alt=media&amp;token=197cd587-73ff-4ac0-9931-99654f6347e2" alt=""><figcaption></figcaption></figure>

3\. Enter a \*\*Connector Name\*\*, for example \`Order created\`. 4. Copy the \*\*Webhook URL\*\* and the \*\*Secret Code\*\*. Your backend sends to the URL, with the Secret Code in the \`x-webtonative-secret\` header. 5. Click \*\*Verify\*\*.

<figure><img src="https://46162361-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MbRbEDU7JrvMAgg52AY%2Fuploads%2FZHycs50BxD53CpdSKoOS%2Fcustom-add-connector.png?alt=media&amp;token=c4e4e680-9416-4cde-a97e-09801e6aae0b" alt=""><figcaption></figcaption></figure>

> Need a new secret? Click **Regenerate Secret** above the Secret Code, and use the new one in your backend.

### Step 3: Send one test request

The window shows **Waiting for the test event**. Send one test request from your backend to the Webhook URL, with the `x-webtonative-secret` header (see [Send webhooks from your backend](#id-3.-send-webhooks-from-your-backend)).

<figure><img src="https://46162361-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MbRbEDU7JrvMAgg52AY%2Fuploads%2FIjNMRkYObWdt1cTEXkSZ%2Fcustom-waiting-for-test-event.png?alt=media&amp;token=52910469-9bd8-4934-9a2d-d9a44232114a" alt=""><figcaption></figcaption></figure>

When the request arrives with the correct secret, the connector is verified.

> **You can close this window.** The connector stays in the list as **Pending verification** and verifies automatically once the test request arrives. No notifications are sent until it's **Active**.

### Step 4: Add External ID (Step 2 of 2)

Tell WebToNative where the user ID is in your payload, using `{{path}}` with dots for nested fields.

1. In **External User ID**, enter the path, for example `{{customer.id}}`. Or click **Pick from test event** `{ }` to choose the field from the test request you sent.
2. Click **Save & Create Template**. The template window opens next (see [Create the notification template](#id-4.-create-the-notification-template)).

<figure><img src="https://46162361-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MbRbEDU7JrvMAgg52AY%2Fuploads%2FyqwHHXv2ncYexW4qee3q%2Fcustom-add-external-id.png?alt=media&amp;token=d97008a9-e6e6-42cf-a65b-7d82b39a98e4" alt=""><figcaption></figcaption></figure>

| Your payload                                  | External User ID        |
| --------------------------------------------- | ----------------------- |
| `{ "user_id": "42" }`                         | `{{user_id}}`           |
| `{ "customer": { "id": "42" } }`              | `{{customer.id}}`       |
| `{ "order": { "customer": { "id": "42" } } }` | `{{order.customer.id}}` |

> **It must match your app.** The value at this path must be the same External User ID your website sets with `setExternalUserId()` for that user.

***

## 3. Send webhooks from your backend

### Request format

| Part                     | Value                                                                                                  |
| ------------------------ | ------------------------------------------------------------------------------------------------------ |
| Method                   | `POST`                                                                                                 |
| URL                      | Your connector's **Webhook URL**                                                                       |
| `Content-Type`           | `application/json`                                                                                     |
| `x-webtonative-secret`   | Your connector's **Secret Code**, copied from the **Add Connector** page                               |
| `x-webtonative-event`    | Optional. A name for the event, e.g. `order.created`                                                   |
| `x-webtonative-event-id` | Optional. A unique ID for this event. If the same ID is sent again, no duplicate notification is sent. |
| Body                     | Your JSON payload. It must include the user ID at the path you set.                                    |

> **Send the secret from your server only.** Never put the Secret Code in your website or app code, where anyone could read it.

### Example

{% tabs %}
{% tab title="cURL" %}

```bash
curl -X POST "https://www.webtonative.com/api/v1/hooks/custom/{connectorId}" \
  -H "Content-Type: application/json" \
  -H "x-webtonative-secret: your-secret-code" \
  -H "x-webtonative-event: order.created" \
  -H "x-webtonative-event-id: order-1001-created" \
  -d '{"customer":{"id":"42","first_name":"Asha"},"order":{"number":"#1001","total":"1499.00","status":"paid"}}'
```

{% endtab %}

{% tab title="Node.js" %}

```javascript
const WEBHOOK_URL = "https://www.webtonative.com/api/v1/hooks/custom/{connectorId}";
const SECRET = "your-secret-code";

await fetch(WEBHOOK_URL, {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "x-webtonative-secret": SECRET,
    "x-webtonative-event": "order.created",        // optional
    "x-webtonative-event-id": "order-1001-created", // optional, stops duplicates
  },
  body: JSON.stringify({
    customer: { id: "42", first_name: "Asha" },
    order: { number: "#1001", total: "1499.00", status: "paid" },
  }),
});
```

{% endtab %}

{% tab title="PHP" %}

```php
$webhookUrl = "https://www.webtonative.com/api/v1/hooks/custom/{connectorId}";
$secret = "your-secret-code";

$body = json_encode([
  "customer" => ["id" => "42", "first_name" => "Asha"],
  "order" => ["number" => "#1001", "total" => "1499.00", "status" => "paid"],
]);

$ch = curl_init($webhookUrl);
curl_setopt_array($ch, [
  CURLOPT_POST => true,
  CURLOPT_POSTFIELDS => $body,
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "x-webtonative-secret: $secret",
    "x-webtonative-event: order.created",         // optional
    "x-webtonative-event-id: order-1001-created", // optional, stops duplicates
  ],
]);
curl_exec($ch);
curl_close($ch);
```

{% endtab %}
{% endtabs %}

Replace the URL and `your-secret-code` with the **Webhook URL** and **Secret Code** from your connector.

### Responses

If the `x-webtonative-secret` header is missing or doesn't match the connector's **Secret Code**, the request is rejected and nothing is sent:

```json
{
  "isSuccess": false,
  "error": "Invalid signature"
}
```

When the secret is correct, the webhook is accepted and the notification is sent, or skipped if no linked user matches (see the connector's **Analytics**).

***

## 4. Create the notification template

After the connector is verified, the **Create a Template** window opens. You can also open it later from the **⋯** menu on the connector row > **Edit Template**.

1. **Connector Name** is filled in and can't be changed here.
2. Enter a **Title** for the notification.
3. Enter the **Message**. Click **Available variables** `{ }` to insert values from the webhook.
4. Enter a **Launch URL**: the page that opens when the user taps the notification (optional). It can be a fixed URL, like `https://yourstore.com/orders`, or a variable.
5. Check the phone preview, then click **Save Template**.

<figure><img src="https://46162361-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MbRbEDU7JrvMAgg52AY%2Fuploads%2F3eKOvdtZMziXlm7yxTho%2Fcreate-template.png?alt=media&amp;token=c05cfc28-6111-4586-b16c-f88e53ac3d30" alt=""><figcaption></figcaption></figure>

### Using variables

Use any field from your payload with the same `{{path}}` syntax. With the example payload above:

* Title: `Order {{order.number}} confirmed`
* Message: `Hi {{customer.first_name}}, your order total is {{order.total}}.`

***

## 5. Manage your connectors

### Connector status

| Status                   | Meaning                                                                            |
| ------------------------ | ---------------------------------------------------------------------------------- |
| **Pending verification** | Created, but not verified yet. No notifications are sent.                          |
| **Active**               | Verified and sending notifications.                                                |
| **Paused**               | Turned off with the **Enabled** toggle. Webhooks are received but nothing is sent. |

### Row actions

Open the **⋯** menu on a connector row:

* **Analytics**: Events Received, Notification Sent, Notification Skipped and CTR for this connector.
* **Edit Template**: change the title, message or Launch URL.
* **Delete**: remove the connector. Its webhook URL stops working.

Use the **Enabled** toggle to pause or resume a connector.

***

## 6. Troubleshooting

* **Verification failed / `"error": "Invalid signature"`**
  * Send the **Secret Code** in the `x-webtonative-secret` header, exactly as copied from the **Add Connector** page (no extra spaces).
  * Make sure you're sending to this connector's **Webhook URL**. Each connector has its own URL and secret.
* **"You don't have any users yet" banner**
  * Call `setExternalUserId()` on login and open the site inside the app once.
* **Notification Skipped increases**
  * The user ID path is missing or empty in the payload.
  * The user hasn't opened the app while logged in, so their device isn't linked yet.
  * The ID in the payload doesn't match the ID passed to `setExternalUserId()`.
  * The connector is **Paused**, or it has no template.
* **`setExternalUserId` rejects with "This function will work in Native App Powered By WebToNative"**
  * The page isn't running inside the WebToNative app. Only call it inside the app.

***

**Notes:**

* Always send the user ID as the same string value you pass to `setExternalUserId()`.
* `removeExternalUserId()` only unlinks the user from the device. It doesn't log the user out or refresh any page; your website handles logout and any redirect.
* To switch to another user, call `setExternalUserId()` with the new ID.
* Need help? Email <support@webtonative.com> or visit [webtonative.com/support](https://www.webtonative.com/support).
