Skip to content

Incoming webhook triggers

An incoming webhook trigger starts a recipe when another service sends a request to a URL on your WordPress site. The data in that request becomes tokens you can use in the recipe’s actions: create a user from a payment processor’s notification, post a form submission from an external tool to Slack, or update a WooCommerce order when your fulfilment service reports a shipment. This article covers the Webhooks > Receive data from a webhook trigger on Uncanny Automator 8.0: the fields in its Set up step, the Test step that listens for a sample request, and how the received keys are used as tokens.

Incoming webhook triggers require Uncanny Automator Pro. The outgoing Send data to a webhook action is in the free plugin.

Use an Everyone recipe

A webhook is an anonymous request: no WordPress user is logged in when it arrives. Incoming webhook triggers therefore work only in a recipe of the Everyone type. In a Logged-in users recipe the picker still lists the trigger but greys it out with the note “This trigger runs for everyone and cannot be used in a recipe for logged-in users.” Choose Everyone in the Select a recipe type modal when you create the recipe; the type cannot be changed later. See Recipe types: logged-in users and everyone.

When the recipe’s actions need a user (adding a role, enrolling in a course, sending an email to the user), a Run recipe as card appears between the triggers and the actions once you add such an action, and it tells Automator which user to act on. You can match an existing user or create a new one from the webhook’s data, for example by mapping the received email key to Match by: Email. Recipes for Everyone explains the card.

Add the trigger

  1. In your WordPress dashboard, go to Automator > Add new recipe, select Everyone, and click Confirm.
  2. Click Add trigger. In the picker, search for Webhooks and select it.
  3. Select Receive data from a webhook. The trigger opens in its Set up step.

The picker on the Trigger step for Webhooks, listing its one item, Receive data from a webhook, with the Pro label

The Set up fields

Webhook URL is the address the other service must send its request to. It is generated for this trigger and cannot be edited; click the copy button beside it and paste the URL into the sending service’s webhook settings. The URL is specific to this recipe and this trigger, so each incoming webhook trigger on your site has its own. As the hint under the field says, it supports PUT, GET, and POST requests.

The Set up step of the Receive data from a webhook trigger with the Webhook URL and its copy button, Data format Auto, an empty Security headers table, and two Fields rows for email and name

Data format tells Automator how to read the body of the request. The options are JSON, x-www-form-urlencoded, Auto, XML, and form-data. A new trigger is set to Auto. Leave it as it is unless the Test step cannot read a sample you know was sent, in which case set it to the format the sending service uses. Auto detects x-www-form-urlencoded, JSON, and XML.

Security headers let you require that every request carries a header with a specific value, so that only the service you gave the URL to can start the recipe. Click Add header and enter the header’s Name and Value; set the same header in the sending service. As the hint under the table says, a request whose headers do not match is ignored. The Security headers section below has a naming caveat.

Fields lists the keys the webhook will send, one row per key with a Key, a Type (Text, Email, Integer, Float, or URL), and an optional Sample value. These rows become the trigger’s tokens. You can type them in by hand with Add pair, or let the Test step fill them from a real request (the next section). The field’s own note says the same: “Manually specify the data that will be received, or use the Test step to listen for a sample webhook.”

Headers is an advanced option for reading a request header, not the body, as a token. Click Add header and enter the Header name; the value of that header is then available as a Header: name token in the actions. Most recipes leave this empty.

Response sets what Automator sends back to the service that called the URL:

  • Default — Automator’s standard success response. This suits nearly every service; most only check that the request was accepted.
  • Custom — reveals Status code, Content, and Content type (JSON by default) so you can return exactly what the calling service expects, for example a specific status code or a confirmation body.
  • Callable function — for developers: the name of a PHP function that builds the response. The field’s note explains what the function receives and must return.

Custom trigger label is an optional name for this step, shown on the recipe canvas and in logs. It does not change how the trigger works.

Capture a sample with the Test step

The quickest way to fill Fields is to let Automator listen for a real request from the sending service. The Test step replaces the Get samples button of earlier versions, and it works the same way: Automator listens at the webhook URL for 60 seconds, and the first request that arrives becomes the sample. Testing triggers and actions covers the Test step in general.

  1. Make sure the recipe is switched off (Recipe off in the top bar). A live recipe owns the webhook URL, so the test cannot listen while the recipe is on.
  2. In the Set up step, check Data format and any Security headers. Fields can stay empty: the test can fill it from the sample. Then click Test.
  3. Click Listen for webhook. The Receive a webhook card changes to Running, the button becomes Stop listening, and a countdown starts at 1:00. The card’s hint says “The recipe must be off while listening.” Save changes (pass tests first) stays disabled until a request arrives.

The Test step of the webhook trigger with the Receive a webhook card Running, the Stop listening button, the countdown, and the disabled Save changes (pass tests first) button

  1. In the sending service, send a test request to the webhook URL. Most services have a “send test” or “test connection” button; if yours does not, trigger the real event once.
  2. When the request arrives, the card shows Test passed and “A webhook was received!” with a Key and Value table of the data it contained, and the footer button changes to Save changes. Listen for webhook is available again if you want a different sample.
  3. Click Use these fields, then Use these fields again in the box that asks “Are you sure?” and says “This will remove your current fields and use the ones in the table above instead.” The builder returns to the Set up step with one row in Fields for each key of the request, with a type and the received value as the sample value. Only the keys listed under Fields become separate tokens (Field#1 followed by the key, and so on), so delete the rows you do not need and check each Type.

The Test step after a webhook was received, with the Test passed chip, the A webhook was received! table of email and name values, the Use these fields button, and the enabled Save changes button

  1. Click Save. The request is also kept as the trigger’s sample, available in later steps as the Webhook sample data token. If you typed your rows in Fields yourself and want to keep them, click Save changes on the Test step instead of Use these fields; with Fields empty, Save changes goes back to the Set up step and asks you to fill in a Key.

If nothing arrives within the minute, the test fails with “No webhook was received within the time limit.” and any earlier sample is kept. Check that the service is sending to the exact URL, that it is sending the security headers you listed, and that Data format matches what it sends, then click Listen for webhook again. Click Stop listening to end a test early.

A trigger saved without a test, with Save on the Set up step or Save without testing on the Test step, runs normally once the recipe is on. The test only gives you sample data to map to tokens; you can type the fields by hand instead.

After you save, the modal closes and the trigger sits under TRIGGERS on the canvas with its On switch. The recipe stays off until you switch Recipe on.

The recipe builder in Diagram view with the Receive data from a webhook trigger and its On switch under TRIGGERS, an empty ACTIONS section, and Recipe off in the top bar

Fill in the fields by hand

When the sending service cannot send a test, or you know its payload from its documentation, enter the keys yourself in Fields. Webhook data is organised as key/value pairs: the key names the piece of data and the value is its content. A request that creates a user might carry:

Key Value
first_name Sam
last_name Rivera
email sam@example.com
username samrivera

Add one row per key, type the key exactly as the service sends it, and choose the Type that matches the value. A Sample value is optional; it is shown when you insert the token so you can recognise the field later.

Nested data is supported. When a value is itself a set of key/value pairs, write the parent and child keys joined with a forward slash. This payload:

{
  "user": {
    "id": "123",
    "first_name": "Sam",
    "email": "sam@example.com"
  },
  "address": {
    "city": "Toronto",
    "country": "Canada"
  }
}

gives the keys user/id, user/first_name, user/email, address/city, and address/country. The Test step writes nested keys in the same form when it captures a sample, so letting it listen is the easiest way to get the names right.

Use the received data as tokens

Each row in Fields becomes a token under the trigger in the token picker, named Field#1 email, Field#2 name, and so on after its key. Open an action, click the ∗ button at the end of a field, and pick the token; when the recipe runs, it is replaced with the value the webhook carried. Each field also has an (original sample) token that returns the sample value you entered or captured rather than the live value, which is useful when you are checking a recipe’s layout before the real data flows.

Two tokens cover the whole request: Webhook body is the raw body as it was received, and Webhook sample data is the captured sample. Any header you listed under Headers appears as Header: name. When Response is set to Custom or Callable function, the response settings are available as tokens too. Managing tokens explains the token picker.

Security headers

A header you add under Security headers must be present, with the same value, on every request, or Automator ignores the request without running the recipe. WordPress normalises header names when it reads a request: it lowercases them and turns dashes into underscores. If a header named x-api-key is not matched, enter it as x_api_key in Automator and try again. Header names are compared case-insensitively, so X-API-Key and x-api-key are the same header.

Other incoming webhook triggers

Several app integrations have their own incoming webhook trigger: Zapier, Make, Integromat, Integrately, IFTTT, KonnectzIT, Typeform, ThriveCart, OptinMonster, and Google Sheets. They all use the same Set up fields and the same Test step described here; only the integration name and icon differ, so the picker shows you which service the recipe is built for. Pick the one that matches your service, or Webhooks > Receive data from a webhook for anything else.

Things to know

  • Switch the recipe on when you finish. The webhook URL only accepts live requests while Recipe on is switched on. The Test step is the opposite: it listens only while the recipe is off.
  • A data format mismatch looks like silence. If the test times out although the service reports a successful send, change Data format to the format the service documents and test again.
  • Each trigger has one URL. Duplicating the recipe creates a new trigger with a new URL; update the sending service after duplicating. A copy made before 8.0 may still carry the original recipe’s URL: the first time you edit and save its trigger, it gets its own URL, so update the sending service then.
  • Deleting stops the URL at once. When you delete a recipe or one of its webhook triggers, its URL stops accepting requests straight away; another webhook trigger in the same recipe keeps its own URL.
  • Get samples is gone. On 8.0 the Test step captures the sample; there is no separate button in the Set up step.

Related: Testing triggers and actions, Recipes for Everyone, Send data to a webhook, Managing tokens, Moving to the new recipe builder

Comments (0)

Leave a Reply

Your email address will not be published. Required fields are marked *

Back To Top