For the complete documentation index, see llms.txt. This page is also available as Markdown.

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.

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.


Link each logged-in user to their device from your website, using the WebToNative Notification functions. Follow the steps on the Webtonative Notifications page:

  1. On login: call setExternalUserId with your user's ID after they sign in, and on page load while they're signed in.

    window.WTN.Notification.setExternalUserId("u123");
  2. On logout: call removeExternalUserId. 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.

    window.WTN.Notification.removeExternalUserId();

The 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.

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.

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**.

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).

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).

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

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:

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.

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.

Last updated