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 lets you send updates to a person's record using a webhook response. You can then use these updated values in the journey, such as in filters or conditions, to guide the person's path.

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

Prepare your webhook response

The Send to webhook action sends a payload to your webhook URL (endpoint) with campaign and 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 can set up your webhook endpoint to extract the contact_id, allowing you to query your database for the person's record and return the necessary field values in the webhook response. This lets you use those values later in the journey for conditions and filters.

Make sure your response payload is valid JSON and includes the person fields and values you want to send.

NOTE: You can send an empty JSON response (containing {} at minimum), but we do require a JSON payload for the response to be considered 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 option, which controls data ingestion queuing, is optional and defaults to false. We recommend setting sync: true to ensure that a contact waits for the fields to update before moving on. If not, they might proceed with outdated data.

NOTE: 

  • You don’t need to provide the merge key (merge_by) or merge key strategy (find_strategy) since the system already knows which contact the data belongs to.
  • You can set the merge strategy (merge_strategy) to either 1 or 2, depending on whether you want to append or overwrite data; the default is 2. The following keys are optional: location, merge_strategy, and sync. If you use the location key, it must be with a custom object.
  • You can update a maximum of 5 fields. You can send more or fewer fields in the payload, but only the fields selected in the webhook shape setup will be updated.

Set up the webhook action shape in your journey or playbook

In your journey or playbook:

  1. Add the action: add the Send to Webhook action.
  2. Select the Data source: Choose the webhook data source that will send the contact data response.
  3. Update contact fields: Check the box to update contact fields.
  4. Add fields: Click Add field to select up to 5 editable Person and/or Organization fields (this includes system and custom fields).
  5. Save your changes: Click Save to complete the setup.
  6. Adjust settings: In the webhook action view, you can modify the following:
    • Trigger frequency: Choose whether this action should trigger only once or more than once (consider the People can be in journey setting for journeys).
    • If this action fails (Journey only): Decide if the person should proceed in the journey or exit if the action fails.

NOTE: 

  • Any issues with the webhook response will be marked as a failure in the webhook action.
  • You can check the webhook data source’s log for the response status code and more details about the webhook action result.
  • For information on response statuses, including whether a response is successful, unsuccessful, or will be retried, see Webhook Response Statuses.