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

# Push Webhook Push Integration with WorldVisa

> Connect a push webhook provider to WorldVisa to deliver push notifications through your own HTTP endpoint or a custom push gateway using a webhook URL and headers.

This guide walks you through the entire process of configuring and using Push Webhook with WorldVisa.

The Push Webhook provider is different from other push providers because it does not depend on a third-party service. Instead, WorldVisa sends push notifications directly to a webhook URL that you control. This approach is ideal if you want full control over how notifications are processed, routed, or stored in your system.

## Configure Push Webhook with WorldVisa

To configure Push Webhook, you must provide an endpoint URL for WorldVisa to call and a secret HMAC key to verify the request's authenticity.

### Step 1: Get your webhook URL and secret key

Before connecting to WorldVisa, you need two things:

* **Webhook URL**: This is your own API endpoint that will receive the `POST` request from WorldVisa. For quick testing, you can use a service like [webhook.site](https://webhook.site/).
* **Secret HMAC Key:** This is a self-generated secret string. WorldVisa will use it to encrypt the payload using the `HMAC SHA256` algorithm and send the hash in the `x-wv-signature` header. This lets you verify that the request is genuinely from WorldVisa. See how to generate a HMAC key.

> [!NOTE]
>
> Your webhook URL endpoint must be able to accept `POST` requests.

### Step 2: Connect Push Webhook to WorldVisa

Next, add these keys to your Push Webhook integration in the WorldVisa dashboard:

**1. Log in to the WorldVisa dashboard**

Open the WorldVisa Dashboard.

**2. Open Integration Store**

On the WorldVisa dashboard, navigate to the **Integration Store**.

**3. Connect a provider**

In the **Integration Store**, click **Connect provider** to begin setup.

**4. Select Push Webhook**

In the **Push** tab, choose **Push Webhook** from the provider list.

**5. Fill in integration fields**

* **Webhook URL:** The endpoint URL that you prepared in Step 1.
* **Secret HMAC Key:** The secret key used to sign webhook calls.

  ![Push Webhook Integration in WorldVisa](https://mintcdn.com/wv-enterprise/l3bkwl1N_3mOn9aW/images/developers/channels-and-providers/push/push-webhook/push-webhook-integration.png?fit=max\&auto=format\&n=l3bkwl1N_3mOn9aW\&q=85\&s=0c736a2982f00f9c9fed99dbc17c1edc)

**6. Create the integration**

Review your credentials, then click **Create Integration** to save.

## Using Push Webhook with WorldVisa

Once configured, you must register a device token for your subscriber and trigger a workflow.

### Step 1: Add subscriber device token

This step is mandatory. Unlike other push providers that generate a unique token, for the Push Webhook, you must provide your own identifier.

Any random string can be used as a device token. This token is included in the webhook payload sent to your endpoint, allowing you to identify which user or device the notification is for.

```bash theme={null}
curl -L -X PUT "${WV_API_URL}/v1/subscribers/<SUBSCRIBER_ID>/credentials" \
-H 'Content-Type: application/json' \
-H "Authorization: ApiKey ${WV_API_KEY}" \
-d '{
  "providerId": "push-webhook",
  "credentials": {
    "deviceTokens": [
      "token1",
      "token2",
      "token3"
    ]
  },
  "integrationIdentifier": "push-webhook-MnGLxp8uy"
}'
```

### Step 2: Send a notification

Now you're ready to send a push notification. [Create a workflow with a Push step](https://docs.worldvisagroup.com/developers/workflow/create-a-workflow.md) and trigger it. WorldVisa sends the notification payload to the webhook URL that you configured.

The example below demonstrates a simple trigger using WorldVisa’s SDK.

```bash theme={null}
curl --location "${WV_API_URL}/v1/events/trigger" \
--header 'Content-Type: application/json' \
--header "Authorization: ApiKey ${WV_API_KEY}" \
-d '{
    "name": "workflowId",
    "to": [
        "SUBSCRIBER_ID"
    ],
    "payload": {
        "custom_message": "This is custom message from payload."
    }
}'
```

## Payload sent by WorldVisa to webhook URL

When you trigger a workflow, WorldVisa sends a `POST` request to your webhook URL with a JSON body similar to the one below.

The payload includes:

* The `title` and `content` from your workflow editor.
* The `target` (the device token you set).
* `messageId`, the WorldVisa message id. The same value is also `payload.__nvMessageId`. Use either value as `eventId` when you [forward activity events](https://docs.worldvisagroup.com/developers/integrations/push/push-activity-tracking.md).
* Your `overrides`.
* The full payload from your trigger.
* The subscriber's profile.

```json theme={null}
{
  "target": ["subscriber-token-for-push-webhook-provider"],
  "title": "Push Webhook message title",
  "content": "push Webhook content body",
  "messageId": "65c0d71c0959a38e8857b999",
  "overrides": {
    "data": {
      "custom_message": "this is custom message from payload push webhook demo"
    }
  },
  "payload": {
    "custom_message": "this is custom message from payload push webhook demo",
    "__nvMessageId": "65c0d71c0959a38e8857b999",
    "__source": "test-workflow",
    "subscriber": {
      // subscriber fields
      "_id": "65c0d71c0959a38e8857b131",
      "_organizationId": "organizationId",
      "_environmentId": "environmentId",
      "firstName": "Pawan",
      "lastName": "Jain",
      "phone": "+123456789",
      "subscriberId": "push-webhook-demo-subscriber-id",
      "email": "pawan+push+web+hook+demo@domain.com",
      "channels": [
        {
          "credentials": {
            "deviceTokens": ["subscriber-token-for-push-webhook-provider"]
          },
          "_integrationId": "integrationId",
          "providerId": "push-webhook"
        }
      ],
      "data": {
        // custom data field of subscriber
        "isDeveloper": "true"
      },
      "deleted": false,
      "createdAt": "2024-02-05T12:39:56.379Z",
      "updatedAt": "2024-02-05T12:54:08.684Z",
      "__v": 0,
      "id": "65c0d71c0959a38e8857b131"
    },
    "step": {
      // digest variables
      "digest": false,
      "events": [],
      "total_count": 0
    }
  }
}
```

## Activity tracking

Push Webhook supports [push activity tracking](https://docs.worldvisagroup.com/developers/integrations/push/push-activity-tracking.md). Enable the **Push Activity Tracking** toggle on the Push Webhook integration.

WorldVisa includes the message id twice on the POST to your webhook URL: `messageId`, and the same value as `payload.__nvMessageId`. Your endpoint delivers the push, so put that id on the notification the device receives. When the subscriber interacts with it, forward the id as `eventId`.

```javascript theme={null}
app.post("/push-webhook", (request, response) => {
  const messageId = request.body.messageId ?? request.body.payload?.__nvMessageId;

  // Include messageId on the notification you deliver, then report it as eventId.
  response.sendStatus(200);
});
```

Accepted `eventType` values are `delivered`, `opened`, `clicked`, `dismissed`, and `failed`. Your backend then calls [WorldVisa's activity endpoint](https://docs.worldvisagroup.com/developers/integrations/push/push-activity-tracking.md#step-3-forward-events-to-WorldVisa-from-your-backend).

## Checking authenticity

If you provided a secret HMAC key during configuration, then WorldVisa will include a `x-wv-signature` header in the request. You can use this header to verify that the request is from WorldVisa and not a malicious third party.

Here is an example of how to validate the hash:

```typescript theme={null}
import crypto from 'crypto';

// secret key added in step 3
const secretKey = 'YOUR_HMAC_SECRET_KEY';

// function to handle webhook url route request
async function acceptWorldVisaPushWebHookRequest(request, response) {
  const payloadSentByWorldVisa = request.body;
  const hmacHashSentByWorldVisa = request.headers['x-wv-signature'];

const actualHashValue = crypto
    .createHmac('sha256', secretKey)
    .update(payloadSentByWorldVisa, 'utf-8')
    .digest('hex');

if (hmacHashSentByWorldVisa === actualHashValue) {
    // handle the notification
    console.log('Request sent by WorldVisa');
  } else {
    throw new Error('Not a valid request');
  }
}
```


## Related topics

- [Expo Push Push Integration with WorldVisa](https://docs.worldvisagroup.com/developers/integrations/push/expo-push.md)
- [Activity Tracking](https://docs.worldvisagroup.com/developers/integrations/push/push-activity-tracking.md)
- [Pushpad Push Integration with WorldVisa](https://docs.worldvisagroup.com/developers/integrations/push/pushpad.md)
- [APNS Push Integration with WorldVisa](https://docs.worldvisagroup.com/developers/integrations/push/apns.md)


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