Quick Start Guide for Event Webhooks

Webhooks are a way to stream data out of OneSignal to your or a third-party destination. For the example in this guide, we will be sending message events to webhook.site, which is a useful tool when testing webhooks because it will accept any configuration of HTTP request and display that HTTP request structure so you can see exactly how the HTTP request is working before pointing it at yours or a third-party API endpoint.

Prerequisites: Have at least one channel set up to send a message with OneSignal

1. Create a new webhook

To create a new webhook, navigate to the Webhooks section of the dashboard. Webhooks are located under the Settings -> Webhooks tab in the dashboard. From there, select the "New Webhook" button.

2. Select the Trigger

Select the “Trigger when any of the following events occur” radio button, and then select the “Select Events" button.

A modal will pop up asking which events you would want like to trigger for the webhook. For testing, we suggest selecting "Sent" or "Received" events for the channels you have configured for your application.

3. Configure the webhook

Go to webhook.site. Find “Your unique URL” in the center of the page. Copy it.

Copy that URL and paste it into the URL field in the configure step on the OneSignal webhook set up.

4. Configure the webhook Body

The webhook body, along with the URL and the headers, will accept liquid syntax. The following is the example payload that we will use.

       "user_id": "{{ event.external_user_id }}",
       "event_id": "{{ event.id }}",
       "event": "{{ event.kind }}",
       "properties": {
         "message_id": "{{ message.id }}",
         "message_name": "{{ message.name }}",
         "message_title": "{{ message.title.en }}",
         "message_contents": "{{ message.contents.en }}",
         "template_id": "{{ message.template_id }}",
         "subscription_id": "{{ event.subscription_id }}",
         "subscription_device_type": "{{ event.subscription_device_type }}",
         "source": "onesignal"
       "originalTimestamp": "{{ event.datetime }}"

Enter liquid syntax into the Custom Body text field.

5. Save and activate

Touch the down arrow on the save button at the bottom of the screen, click the option save and exit. This will bring you back to the webhooks page under settings.
Locate your webhook from the list of webhooks and navigate to it by clicking on it
In the top right corner click on the actions dropdown, select activate from the drop down menu

Confirm that the webhook is active

6. Send a message (prerequisite)

Send a message from your OneSignal application. This will cause events to be triggered from the webhook you have just configured. For more information on how to send a message, please check out How to Send a Message.

7. Results

On the OneSignal webhook page you can see the successful webhook sends:

Navigate back to webhook.site

On webhook.site you will be able to browse all of the HTTP requests that were triggered by the message that was just sent, along with their payload and headers.


You have now successfully tested your webhook!