Working with webhook triggers

NOTE: Webhook triggers are very powerful and without proper configuration, quite dangerous. For this reason, webhook triggers are disabled by default in WunderAutomation. To enable webhook triggers, go to AutomationSettingsGeneral and enable webhooks.


Webhook URL

Each webhook trigger has to have a unique link. The link consists of two parts:

Webhook slug

The webhook slug is the base URL for all incoming webhooks, it’s the first part of the webhook URL after the domain name. The default value is ‘wa-hook’ but you can modify it to any value that you see fit.

Webhook unique identifier

To differentiate between webhooks, each webhook gets a unique identifier. The default identifier value is a randomized 12 character long string. Just as with the slug, you can modify this to a value you see fit. Please be aware that WunderAutomation does not check for duplicate webhook keys. If you define two workflows with the same unique key only one of them will be executed and it’s not possible to determine which one.


The WordPress base URL, the webhook slug, and the unique identifier are combined into the unique URL for a webhook.


Webhook security is very important. WunderAutomation provides three different authentication mechanisms to authenticate an incoming HTTP request. It’s possible to use zero, one, or more authentication mechanisms.


Basic authentication

Classic HTTP basic authentication as defined in RFC 7616. The basic authentication method is enabled by default with a random username and password.

Please note that this method sends username and password in (almost) clear text. Should only be used on sites with SSL (HTTPS) enabled.

Parameter Description
Username The username.
Password The password.

API key in header

Authenticates by checking a given HTTP header (defined in the workflow) for the correct API key.

Please note that this method sends the API key in clear text as an HTTP header. Should only be used on sites with SSL (HTTPS) enabled.

Parameter Description
HTTP header The name of the HTTP header where WunderAutomation should look for the API key. Example: X_API_KEY.
Value The API key. Note that this value is unique and different for each individual webhook workflow.

HMAC Signed payload

Authenticates by verifying that an HMAC signature of the payload (posted data) signed with a shared secret key matches with the value provided in the header. The payload is signed using the SHA-1 algorithm (as it’s used by ie GitHub).

This method never sends any secrets between the client and server, it is considered the safest of the three available methods.

Parameter Description
HTTP header The name of the HTTP header where WunderAutomation should look for the signature. Example: X_HUB_SIGNATURE.
Secret The shared secret between the server (WunderAutomation) and the client (the application/script that calls the webhook).


Sending a valid HTTP request to a webhook using HMAC signed payload authentication:

View this gist on GitHub

Parameters and objects

A webhook trigger can inject up to four different objects into the workflow, a post, an order, a user, or a comment. It’s possible to inject more than one object into the workflow, but only one object of each type.

The object the webhook provides is determined by the parameters passed to the webhook:


The above parameter configuration assumes that the client that calls this webhook provides two parameters; post_id and user_id. The parameters can be passed as REQUEST URL parameters (in the request URL), as x-form-encoded parameters in the REQUEST BODY, or as JSON in the request body.


The above URL would trigger the workflow with a webhook trigger ID = "abc123abc123" and inject the post with ID = 999 and user with ID = 123 into the workflow. The filters and actions in that workflow can then use these two objects for filtering and like parameters.

Identifying the objects

Objects can be identified based on matching different properties with the parameters that are passed into the webhook. The parameter that is passed in to identify an object is matched in the following order.

Object type Properties Comment
post 1. ID, 2. Post slug Note that slug can be unreliable.
user 1. ID, 2. Email, 3. Login name
comment 1. ID
order 1. ID, 2. Order key Order keys.

Example: If an incoming webhook has the parameter "user=adam", WunderAutomation will:

  1. See if there is a user with the numerical ID of ‘adam’ (will fail, ‘adam’ isn’t numerical).
  2. If not, look for a user with the email address ‘adam’ (will fail, ‘adam’ is not a valid email address).
  3. If not, look for a user with the login name ‘adam’. If this login name exists, the corresponding user object will be added to the object context.

Response codes

The response is sent as JSON or plain text depending on the request Content-type header. In both cases, the following parameters are returned:

Code Message HTTP status Description
fail Unknown hook code 404 No webhook trigger found with the unique ID passed.
fail Objects not found 400 One or more of the required objects was not resolved to a valid WordPress object.
fail Authentication failed 401 Authentication failed.
ok Success 200 The workflow was initialized as expected and the actions were executed.