Go to ortto.com
Home Campaigns Managing campaigns How to update a person's data from a webhook in a journey or playbook

How to update a person's data from a webhook in a journey or playbook

The Send to webhook action in a playbook or journey campaign enables you to send, via a webhook response payload, field value updates to a person record. You can then use the updated field values within the journey, such as in filter or condition shapes to determine the person’s path through the journey.

NOTE: This functionality applies to the webhook action in a playbook or journey only, not the webhook data source.

Prepare your webhook response

The Send to webhook action will send a payload to your webhook URL (endpoint) containing campaign and person (contact) data, similar to this:

json
 
"campaign_id": "<value>",
"campaign_name": "Journey with Webhook response",
"contact_id": "<value>",
"email": "contact@example.com",
"id": "<value>",
"run_id": "<value>",
"shape_id": "1",
"shape_title": "https://webhook.example",
"time": "2023-12-13T23:28:09.895030588Z",
"webhook_id": "<value>"

You might have your webhook endpoint configured to extract the contact_id value so that you can query your own database for the person's record, and return the field values you need in the webhook response (e.g. so you can use these values later on in the journey, such as for condition and filter shapes).

Your response payload must be valid JSON, containing the person fields and values you wish to send. 

NOTE: If needed, you can send an empty JSON response (containing {} at minimum). However, we do require a JSON response payload to consider the response successful.

For example, your webhook response might look something like this:

json
 
{
"fields": {
  "str::first": "Jenny",
  "str:last": "Sprinter",
  "geo::country": {
  "name": "Australia"
  }
  "phn:cm:examplephone": {
    "c": "61",
    "n": "499999999"
  }
},
"location": {
  "custom": {
    "country_name": "Australia",
    "region_name": "Sydney",
    "city_name": "Gladesville",
    "position_name": "Central Perk Cafe",
    "lat": -33.83333,
    "lng": 151.13333
    }
},
"merge_strategy": 2,
"sync": true
}

To populate your webhook response, find person or organization field IDs in the API reference guide, or in your account at Settings > Customer data > Fields.

NOTE: The field sync (which determines whether or not data ingestion is queued) is optional and, unless specified, is set to false.

We recommend setting sync: true to ensure that a contact waits at the shape for the fields to be updated before continuing, otherwise they could continue to the subsequent shapes before the update is ingested, and use old data.

NOTE: 

  • You don’t need to provide the merge key (merge_by) or merge key strategy (find_strategy) values, because the system will already know which contact the data is associated with.
  • You can, however, set merge strategy (merge_strategy) 1 or 2 you like (so you can choose whether to append or overwrite data); the default value is 2.
  • The following keys are optional: location, merge_strategy, sync.
  • If you wish to use the location key, it can only be used with the custom object (per the example above). 
  • The maximum number of fields that can be updated is 5. Your response can send more or fewer than 5 fields in the payload; only those that are selected in the webhook shape setup in the journey will be updated.

Set up the webhook action shape in your journey or playbook

In a journey or playbook, add the Send to webhook action.

  1. At Webhook, select the webhook data source which will send the response containing contact data.
  2. At Update contact fields, select the checkbox. 
  3. Next, click Add field and select up to 5 Person and/or Organizations fields. Note that only fields which are editable can be added (such as system and custom fields).
  4. Click Save to finish.
  5. In the webhook action view, adjust the following settings as required:
    • This action can occur — Allow this action to trigger Only once or More than once (for a journey, consider also the People can be in journey setting).
    • If this action fails (Journey only) — Do you want the person to proceed in the journey, or exit the journey?

NOTE: 

  • Any issues regarding the webhook response will be interpreted as a Failed result at the webhook action. 
  • You can check the webhook data source’s Log for the response status code and more detail on the result of the webhook action.
  • See the Webhook response statuses documentation for information on whether a response is marked successful, unsuccessful, or will be retried.