Journey webhooks

With Journey Webhooks, you can send HTTP requests from OneSignal Journeys to your servers—or any internet-accessible service—at precisely the right moment in a customer’s lifecycle. Configure the HTTP method, URL, headers, and body content to match your integration requirements. Requests can be dynamically personalized with user-specific data, making webhooks a powerful way to sync your Journeys with the rest of your marketing stack.

​

Requirements

Before events can be sent, make sure:

• Contact our sales team for access.
• The URL/IP address is valid and reachable over HTTP or HTTPS.
• Endpoints are publicly routable (i.e., not behind a firewall or on localhost).
• Domains must have a valid top-level domain (e.g., .com, .org, .net).

​

Setup

Once your Journey is created, follow these steps:

1. Navigate to Data > Webhooks in the OneSignal dashboard.
2. Click to create a new webhook.
3. Define the following:
   • HTTP method (usually POST)
   • Target URL
   • Custom headers (e.g., for authentication)
   • Body content (plain text or JSON, optionally using Liquid)

​

Disallowed headers

You cannot set the following headers:

• content-length
• referer
• metadata-flavor
• x-google-metadata-request
• host
• Any header starting with x-onesignal

​

Testing webhooks

You can also test your endpoint manually using a tool like curl:

curl -X POST https://yourserver.com/webhook \
  -H "Content-Type: application/json" \
  -d '{ "user_id": "abc123" }'

Useful for validating that your endpoint is reachable and functioning before adding it to a Journey.

​

Personalization

All webhook fields support Liquid syntax, allowing you to dynamically insert user and subscription data into the request.

Example body:

{
  "user_id": "{{ user.onesignal_id }}",
  "email": "{{ user.tags.email }}",
  "language": "{{ user.language }}"
}

​

User data reference

The following properties from the user object are available in webhook fields via liquid syntax:

​

Adding a webhook to a Journey

1. After creating and testing your webhook, open your Journey.
2. Add a Webhook step where needed.
3. Select the webhook you configured earlier.

Each time a user reaches that step, the webhook fires with their personalized data.

​

Debugging and logs

​

Webhook stats

Go to the webhook’s Stats tab to view how your webhook is performing. This includes:

• Total events sent
• Response time trends
• Status code distribution

​

Logs tab

For more granular insights, the Logs tab displays:

• Recent request/response data
• Status codes and error messages
• Headers and payloads (where applicable)

​

Retry logic and disabling behavior

OneSignal retries failed webhook requests for recoverable errors (e.g., 429 Too Many Requests). Retries happen with increasing delays.

If retries repeatedly fail, the webhook is marked as permanently failed and no further attempts are made.

​

Automatic disabling

If a webhook consistently fails, OneSignal disables it to prevent further issues. Admins receive email alerts and a dashboard banner before and after a webhook is disabled. If this happens, make sure to spend some time troubleshooting, fixing and then testing the webhook before re-enabling it.

It is important that the API which ingests an webhook is able to handle the volume of events which is produced by message sends. Reviewing the volume of message sends that are produced by your app will reflect the performance required of your API.

​

Performance guidance

• Slow or overloaded endpoints (especially with 429 responses) can trigger disabling.
• APIs should record events quickly and defer additional processing to avoid timeouts.
• Volume scales with user activity—ensure your endpoint can handle this throughput.
• Use the event.id value (available as a header or in body) to deduplicate incoming events.

​

Tips for success

• Connect webhooks to your own servers first, not directly to third-party services.
  • While OneSignal webhooks can call any public API, routing through your own server gives you more control.
  • It’s easier to debug, add logging, handle authentication, and throttle or queue requests as needed.
  • Third-party services may rate-limit or block requests if volume spikes, and OneSignal does not manage those limits.
• Webhook execution happens immediately as users reach that step in the Journey.
  • If many users hit a webhook step at once, OneSignal will send a burst of HTTP requests without rate limiting.
  • This can easily overwhelm external services, trigger rate limits, or incur unexpected charges.
  • Consider building a lightweight API layer or queueing proxy that can:
    • Ingest webhooks reliably
    • Apply rate limits or batching
    • Route requests to your third-party services gracefully
• Use third-party APIs carefully:
  • Most popular tools (e.g., Slack, Twilio, Segment) offer public HTTP APIs.
  • Review their rate limits, authentication requirements, and error handling strategies.
  • Search for code examples in their docs to see what your webhook request should look like.

​

Securing your webhook

To ensure that requests are coming from OneSignal and have not been tampered with:

• Use an HMAC signature header with a shared secret
• Add a custom auth token in the header and verify it server-side

​

Related links:

• Using liquid syntax
• Users