Webhooks simply POST flow data structured as JSON to an external service every time a contact reaches a Call Webhook RuleSet. When a user reaches a Call Webhook RuleSet, we'll call the URL you've configured, passing it all of the variables collected up to that point in the flow. See the Flow Event webhook documentation for a full list of the values included. If your service returns a JSON object, Community Connect will save its values and allow you to access them in the flow using the @extra variable prefix.
For example, the Order Status Checker sample flow in your account asks the contact for their order number, then looks it up by POSTing it to an example external service that we've configured. That service responds with a JSON object similar to the following:
{
"status": "Shipped",
"number": "CU001",
"name": "Ben Haggerty",
"ship_date": "October 9th",
"delivery_date": "April 3rd",
"description": "Vogue White Wall x 4"
}
You're then able to reference these keys anywhere in the flow via the @extra variable prefix, e.g. @extra.status or @extra.number.
Configuring a 'Call Webhook' RuleSet
In this example, we'll show you how to add a webhook to a flow. You can follow along using the Order Status Checker sample flow located on the flows tab within your account.
Generate a Flow Field
Create a Wait for response RuleSet that collects the target value from your contacts and saves it as a flow variable. In the example below, the Wait for Response RuleSet collects our contacts' order numbers and save them as the flow variable@flow.lookup_response.
Make a Request
Create a Call Webhook RuleSet, toggle the request to "POST", and enter your URL:
If your service returns JSON, it'll be stored to the Lookup Webhook flow variable @flow.lookup_webhook. The action log within the simulator will show you the returned JSON object:
Evaluate the External Variable
Next, create a Split by Expression RuleSet that evaluates one of the returned values against a response rule. In the example below, because the status key (@extra.status) can only contain one of three values (shipped, pending or cancelled), we can use the has all of the words response rule to discern which value is present for the contact:
If the returned status value matches "shipped", "pending" or "cancelled", the contact will be directed accordingly. Otherwise, the contact will pass through the "other" category and receive a prompt to resubmit an @flow.lookup_response value:
Viewing Webhook Events
To view Webhook events, navigate to your account page, click the Webhook icon, then click the "API Log" button in the bottom right corner:
Your recent events will be listed chronologically with event type, status, channel values and attempts provided:
You can click an event to view the contents of the request and the corresponding JSON properties:
Troubleshooting
Unsuccessful requests are captured by the 'Failure' category. We connecting it to a Send Email action to ensure they you're alerted the moment an error occurs.
There are lots of tools available that can help you to mimic, intercept and capture webhook requests so you can understand and fix problems, here are just a few of them:
Give it a Try
Use our webhook simulator to test your URL's performance when called by Community Connect.