🚧

This feature is currently in Private Beta

Please reach out to your OneSignal account representative if you'd be interested in participating in the beta program for this feature.

Introduction

OneSignal’s Event Webhook allows you to stream data out of OneSignal to your chosen destination. Webhooks are a great way to connect OneSignal to other products within your marketing ecosystem, sending events in real-time. This enables your team to trigger corresponding messaging, maintain records, and much more.

Setup

You can configure a new webhook for your OneSignal application under Settings → Webhook.

Selecting Webhook Triggers

Webhooks at OneSignal have two types of triggers, Journeys and Events, this guide is for event webhooks, so select the second radio button, “Trigger when any of the following events occur."

Next click “Select Events” and select your choice of events that will trigger a webhook. The data that may be sent with these events is all similar enough that you can send webhook triggered by multiple channels through the same webhook. Another approach would be to define multiple webhooks each for a single channel or event for more granular control or to reduce the scale of data sent.

Configuring the webhook

Select the HTTP method, the URL, and add headers for the webhook this is where authentication will often be. The URl and Headers can contain liquid syntax which will come from both the user properties, but also properties of the webhook.

You may add any headers needed, common examples being an Authorization key, with values like Basic {{YOUR_TOKEN}} or Bearer {{YOUR_TOKEN}} where YOUR_TOKEN is provided by your system or 3rd party. OneSignal does not provide encryption services.

Body

The body for an event webhook will be JSON. The body JSON can be defined either as individual key/value pairs or as an editable code block. To change the input method use the first dropdown under the body heading and select the custom body.

On the right, you can see an example cURL request built from what has been input during webhook setup

Personalization

You can personalize all fields in your webhook using information about the user and the message on whose behalf it was triggered. This gives you the flexibility to use webhooks for nearly any use case.
​
The webhook event provides access to objects such as event, message, and user, each with a specific structure. To exemplify, if you need to embed the External User ID in your webhook URL, you can use a template like: ​<https://example.com/webhook/user/{{user.external_user_id}}>

This will dynamically inject the user's External User ID into the URL. Similarly, for more personalized content, you can utilize specific tags from the user.tags object.

Examples include:

• The template{{user.tags.favorite_color}} could customize messages based on the user's preferred color.
• The template {{user.tags.first_name}} {{user.tags.last_name}} could be used to include the user's full name.
  ​

Event

The event object includes the following properties:

{
  "id": "{{ event.id }}",
  "kind": "{{ event.kind }}",
  "app_id": "{{ event.app_id }}",
  "subscription_id": "{{ event.subscription_id }}",
  "subscription_device_type": "{{ event.subscription_device_type }}",
  "external_user_id": "{{ event.external_user_id }}",
  "timestamp": {{ event.timestamp }},
  "datetime": "{{ event.datetime }}"
}

{
    "id": "6f24fcf2-0467-4d4f-9d62-567f8ed0deb9",
    "kind": "message.push.sent",
    "app_id": "3beb3078-e0f1-4629-af17-fde833b9f716",
    "subscription_id": "d1eec82d-453a-4a6d-8d26-622cf18584e6",
    "subscription_device_type": "iOS",
    "external_user_id": "THE EXTERNAL ID",
    "timestamp": 1708559416,
    "datetime": "2024-02-21T23:50:16+00:00"
}

Message

The message object is designed to keep you informed of the messages sent to the end-user. It includes properties like id, template_id, and content which contains the actual text of the message.

{
  id: 'f3c9cd09-10d7-4f59-b9bc-66e16607f1d5',  
  name: 'Discount Message 50% Off XYZ',  
  title: 'Claim 50% Off Today',  
  contents:  'Go to our website to claim 50% off',  
  template_id: 'a6d8bc10-b9bc-4f59-10d7-66e16607f1d5'  
}

User

The user object contains user-specific data, such as external_user_id, Data Tags, and other user details.

{
  external_user_id: 'example123456',  
  language: 'en'  
  tags: {  
    key: value,  
    ...
   }
}

​
Check out Message Personalization for more details about how to use liquid templating in general.
Remember that each request represents one specific user; OneSignal will send a new copy of this request every time a user hits the correct step in your journey. Using the tag selector and the liquid templating language, you can customize the request payload with user information.

Results & Debugging

You can see how your webhook performs over a period of time on the webhook report page under the 'stats' tab. This will include all-time numbers, the current status of your webhook, and time series data showing what kind of responses the hook has been receiving. Any HTTP response in the 200 range indicates an event was successfully received, while responses in the 400s and 500s indicate errors. A timeout means the server on the other side didn't manage to respond within a reasonable amount of time so OneSignal closed the connection and assumed it failed.

You can see a sampling of recent requests under the 'logs' tab for even more detail. This will show actual requests and the responses from the other side (if applicable). If your webhook has issues, this is a great place to look first. If you need to change/update your webhook, you can edit it on the form page and send test requests to see the full details you need until you can get it right.

Retries / Disabling

If your webhook has a failure rate of 300/5 minutes, OneSignal will disable the webhook so you can fix any errors and re-enable.

When a webhook request fails for any reason (anything from connectivity issues to not being configured correctly to an error on the receiving server) OneSignal will retry sending the event again after a short delay. This will happen a few times with increasing delays between requests. If enough retries fail in a row, the hook will be marked as 'failed permanently' and will no longer be retried.

If too many separate requests fail in a row, this is probably because of an issue on the receiving end; the receiving end could have errors or have changed/disabled something. OneSignal will continue to send requests to a certain point, but if the requests continue to fail, the webhook might be disabled by OneSignal. If this happens, make sure to spend some time troubleshooting, fixing and then testing the webhook before re-enabling it.

Tips for Success

1. You typically will want to have webhooks connect to your own servers, not third party services.
   1. While there is nothing wrong with connecting directly to a third party the following can be harder to manage:It will be more challenging to configure/debug
   2. Volume of requests will not be managed in OneSignal.
      1. Webhooks will be sent out as fast as users hit the steps in your journey and this might overwhelm other services, hit rate limits, or run up YOUR bill unexpectedly. This is especially common when trying to use another messaging channel for something like SMS. The flexibility of webhooks means OneSignal does not know what you're trying to accomplish with them so you may want to create a simple service of your own that accepts the webhook requests then correctly handles your third party connection limits, rate limits, and queue.
2. Many services have public HTTP APIs which means you can connect to them with a webhook; look for their API docs and examples of how to make an HTTP request to find the right place to get started.