Webhook

Developer assistance needed

You’ll need your developer team’s help to configure the Webhook element. Share this guide with them to get started.

Webhooks let you send journey data to external services such as analytics, CRM systems, and marketing tools. You can:

• Notify external systems when a customer takes an action in the journey
• Send customer data to analytics tools
• Trigger third-party emails, SMS, or WhatsApp on specific journey events

Note

Check out some examples of how to implement webhooks for different use cases and services: Webhook Integration Samples

How to set up the Webhook element

Add the Webhook element

Drag-and-drop the Webhook element to the canvas. Place Webhook anywhere you’d like, keeping in mind what journey info you’re going to send to a third-party service.

Name the Webhook step and specify the request URL and type

In the STEP NAME field, enter a name for the webhook. It might be handy to name webhooks according to the services they send data to or the use case.

Next, in the URL field, specify the request URL to which the data should be sent. Next to the URL field, select the request type from the REQUEST TYPE dropdown: GET or POST.

Note

The URL must be publicly reachable. Pushwoosh rejects private, internal, loopback, and link-local addresses, including cloud metadata endpoints, whether they come from the URL itself or from a redirect it points to. See Timeout, retries, and failed requests for what happens when a request is blocked.

Configure headers

In the HEADERS section, set the content type.

By default, the content type is application/json. If the service you’re sending the webhook to requires another content type, enter the appropriate one in the Content-Type header value.

Examples of content types are:

• x-www-form-urlencoded
• text/plain
• text/xml

Add additional headers if needed by clicking + ADD HEADER. You can remove any header by clicking the ‘x’ icon next to it.

Add whatever authentication header your endpoint requires, for example:

• Authorization: Bearer <token>
• X-Api-Key: <key>
• Authorization: Basic <base64(user:pass)>

Only a static secret in a header is supported. OAuth2 token-exchange flows, mTLS, and request signing on the Pushwoosh side aren’t supported. You can also restrict the endpoint to Pushwoosh’s IP addresses instead of, or in addition to, a header secret. See Pushwoosh IP addresses.

Note

Need to pass a per-user value, such as a token or ID, instead of a fixed secret? Insert a Dynamic Data macro into the URL or the JSON body, for example as a query parameter or a body field your endpoint reads.

For HTTP Basic authentication specifically, do the following:

1. Open a plain text editor and type your username and password with no spaces, separated by a colon. For example: <username>:<password>
2. Encode this string into Base64.
3. Copy the resulting Base64 string (for example, <base64-encoded-string>).
4. In the webhook settings, add an Authorization header with the value: Basic <base64-encoded-string>. Make sure there is a space after the word “Basic”.

Mark a header value as secret

Click the eye icon next to a header’s value to mask it. Pushwoosh hides that value everywhere it would otherwise leave the service: in the UI, in API responses, and in the journey’s version history.

• Automatic masking. Headers whose names look like credentials are masked automatically, even if you never click the eye icon. This includes Authorization, Proxy-Authorization, Cookie, Set-Cookie, and any name containing token, secret, password, credential, auth, or api-key/api_key/apikey (with a hyphen, an underscore, or no separator).
• Change a masked value. Click into the field showing •••••••• and type the new value. There’s no button to reveal the stored value. The eye icon stays locked while the mask is shown. To remove the secret flag from a header, type a new value first, then click the icon.
• Rename a masked header. Renaming a header whose value is currently shown as the mask clears that value. Enter it again under the new name. Renaming a header that currently holds a value you just typed keeps that value.

Note

In the journey’s version history, a change to a secret header’s value shows the mask on both sides of the diff. You can tell that a secret header changed, but not what it changed from or to.

Add the JSON request body

In the DATA section, enter your JSON request body. Make sure the request body is in correct JSON format.

Note

If there is no value for the Dynamic Data placeholder when the POST request is sent, the null value will be transmitted.

Example:

{
  "hwid": "{{device:hwid}}"
}

Use dynamic data and macros

The DATA BUILDER panel allows you to insert dynamic information (such as user, device, tag, or event data) directly into your JSON request body. With Dynamic Data, you can include values specific to the individual user progressing through the journey.

For this:

1. Select a category. You can pull data from three categories:

• Device: Use Device data when you need technical information tied to the user’s device.

• Tag: Use Tag data when you want to send information stored in the user profile.

• Event: Use Event data when the webhook should send values from the triggering event of the journey.

Note

Values from the triggering event stay attached to the traveler for the rest of the journey, including across a Time Delay. They’re only lost if the traveler leaves the journey, for example on a cancel event, an exit, or when the journey ends. If a traveler goes through the same Webhook step more than once, the new response overwrites the value it mapped last time.

2. Select a parameter (for example, HWID, favourite category, etc.).
3. Pushwoosh generates a macro that looks like this:

{{tag:Language}}

4. Copy the macro and paste it into your JSON body in the DATA section.

When the webhook runs in a live journey, Pushwoosh automatically replaces the macro with the actual value for that user.

Map webhook response data to variables

Besides sending data out, the Webhook element can also capture data from the response it receives and turn it into variables. These variables can then be used later in the journey. For example, set a tag with Update user profile, or schedule a Time Delay based on a value returned by the external service. For a full journey example, see Using webhook response data in your journey.

In the RESPONSE MAPPING section, click + ADD MAPPING and fill in two fields for each value you want to capture:

• Path: the location of the value inside the response JSON body
• Attribute: the name you use to reference this value later in the journey

For example, if your CRM responds with:

{
  "data": {
    "user": {
      "id": "789xyz"
    }
  }
}

Set Path to data.user.id and Attribute to crm_user_id to capture that ID.

Note

A few things to know about mapping:

• Path is a plain dot-separated path: object keys, and for arrays either a numeric index (results.0.code) or * for every element (items.*.item_name). It doesn’t support filters, so within an array it’s either one index or all of them, never a subset.
• Values are stored exactly as they come from the JSON response (text, number, or true/false). There is no type conversion: 100 maps as a number, but "100" maps as text and won’t work in a numeric comparison. If you plan to use a value as a date in a Time Delay element, make sure your service returns it in one of the date formats Time Delay supports. A decimal number (for example 19.99) can be saved into a Tag of the Price type.
• If the response isn’t valid JSON, or a Path doesn’t match anything, the corresponding variable isn’t created for that user. No error is shown, and the Webhook step still completes normally.

Map every element of an array

Put * where the response has an array to capture a value from every element instead of just one, for example items.*.item_name. What you put in Attribute decides the shape of the result:

• Include {n} in Attribute (for example item_{n}) to get one attribute per element, counted from 1: item_1, item_2, item_3, and so on. {n} can sit anywhere in the name, for example item_{n}_sku.
• Leave {n} out (for example item_names) to join every element into a single attribute, separated by commas: Sofa, Lamp, Rug.

For example, if your CRM responds with:

{
  "items": [
    { "item_name": "Sofa" },
    { "item_name": "Lamp" },
    { "item_name": "Rug" }
  ]
}

Set Path to items.*.item_name and Attribute to item_{n} to get item_1 = Sofa, item_2 = Lamp, item_3 = Rug. Set Attribute to item_names instead to get a single item_names = Sofa, Lamp, Rug.

Note

If the rest of the Path doesn’t resolve for an array element (for example, one entry missing item_name), that element is skipped, and the numbering closes the gap: the next matching element still becomes the next number rather than leaving a gap. A mapping over an array only captures its first 50 elements. Anything past that is dropped.

A numbered attribute like item_3 can be referenced anywhere a regular webhook response attribute can: in Update user profile, in a Time Delay, or in Dynamic Content.

Caution

Response bodies larger than 64 KB aren’t processed for mapping at all. Keep the response your endpoint sends back reasonably small if you plan to map values from it.

Using webhook response data in your journey

Timeout, retries, and failed requests

Pushwoosh waits up to 10 seconds for a response. The whole Webhook step, including sending the request and processing the response, is capped at 30 seconds.

Retries

On a 500, 502, 503, or 504 response, or a network error, Pushwoosh retries the request once before giving up. Any other non-2xx response is not retried.

Note

A retry resends the exact same request. Make your endpoint idempotent (safe to receive the same call twice) if a duplicate, such as charging a payment or creating a record twice, would be a problem.

Rate limits

Pushwoosh limits how many webhook requests an account can send per second. The limit is sized well above real traffic peaks, so normal journeys aren’t affected. A burst that exceeds it waits briefly for room before failing.

Endpoint cooldown

If an endpoint fails several times in a row, Pushwoosh stops sending it requests for a while instead of retrying a broken endpoint on every traveler, starting at 30 seconds and doubling on further failures up to 5 minutes. A single successful request clears this and resumes normal delivery.

What happens when a request fails

The Webhook element has no separate branch for failed requests. Any of the following drops the traveler from the journey at this step:

Cause	What triggers it
Blocked endpoint address	The URL is private, internal, loopback, or link-local, including cloud metadata endpoints
Rate limit	The account’s per-second webhook request limit is exceeded and no room opens up during the brief wait
Endpoint cooldown	The endpoint failed several times in a row and Pushwoosh is temporarily skipping it
Timeout	No response within 10 seconds, or the step exceeds its 30-second cap
Network error	The request couldn’t reach the endpoint at all
Non-2xx response	The endpoint returned an error status that isn’t retried, or was retried once and failed again

See Request error.

If you can’t afford to lose travelers here, have your endpoint always return a 2xx response and put any failure state in the response body instead, for example as a value your Response mapping can pick up.

This applies to every Webhook step, including ones set up before this change. An endpoint address that now matches the blocked-address rule above will start failing the same way.

Unlike a failed request, a response that arrives but doesn’t map cleanly, such as invalid JSON, an unresolved Path, or a body over 64 KB, does not drop the traveler. See the note under Response mapping above.

Test the Webhook

Click Test webhook to verify that your webhook configuration is correct and the request is sent successfully.

If a header still shows the stored mask, Pushwoosh fills in the real, saved value for the test request. The value never appears in your browser.

This substitution only works for a header already saved on this exact step. A step you haven’t saved yet, or one you just copied, has no saved value behind the mask, so Pushwoosh sends the test request without that header.

Save your configuration

Click Apply to save your webhook configuration.

Calls log

Open the Calls log tab in the point’s drawer to see what Pushwoosh actually sent for this step: time, user, result, and duration, going back 30 days.

Note

Calls log only records requests Pushwoosh actually sent. A traveler dropped before that point, for example by the rate limit or an endpoint cooldown, doesn’t get a row here.

Filter by result (Success, HTTP error, No response) or search by the exact User ID or HWID. Click a row to expand it and see the request (method, URL, and body) and, depending on the outcome, either the response (status and body) or the error text. Duration covers the whole step, including time spent on an automatic retry.

Caution

Request and response bodies over 4 KB are cut, marked with …[truncated]. Any value Pushwoosh sent in a header, such as a bearer token or API key, is replaced with [redacted] everywhere it would otherwise appear: in the URL, the bodies, and the error text, not just in a headers field.