Configuring a webhook

Ortto’s webhooks:

allow Ortto to interact with 3rd-party applications so that these applications can consume and perform actions from your Ortto account,
can be configured to trigger these actions from playbook and journey campaigns, as well as activities, and
as a data source, can be disconnected at any time through your Ortto account’s user interface (UI), thereby preventing any actions from being sent to its configured 3rd-party application until the webhook is reconnected.

Each webhook (action) sends a configurable HTTP request carrying Ortto data in its payload to these 3rd-party applications' application programming interfaces (APIs). The following key attributes can be configured for each webhook:

the URL of the 3rd-party application,
the HTTP method,
any additional activity data relevant to the payload, and
any additional people and custom fields to the request body payload.

Create your webhook

To create a webhook in Ortto:

Navigate to the Data sources page, then click New data source.
On the Connect a data source page, select All data sources > Webhook (advanced). (Or use the search bar to look for "webhook".)
On the webhook Setup page, complete the following fields:
- Webhook name — the name of this particular webhook configuration, as it will appear on the Data sources page.
- Endpoint:
  - Webhook URL — the URL of the 3rd-party application that will consume Ortto data sent in HTTP requests through this webhook.
  - HTTP method — the HTTP method used to send HTTP requests through this webhook.
  - Send activity payload if relevant — ensure this checkbox is selected so that any additional activity data that this webhook is triggered by is sent in the payload of its HTTP requests. This includes the activity that triggered entry to the journey containing the Webhook action shape, when the Journey entry criteria is "X activity occurs".
If the 3rd-party application’s API consuming Ortto data through this webhook requires:
- Basic auth to be sent with each request, then click Basic auth > Add basic auth and specify the Username and Password required to authenticate each request sent by this webhook.
- Any additional custom headers sent with each request, then click Custom headers > Add header and specify the Key and Value for the required header, repeating this process for each header required.
- Any additional fields sent with each request, then click Fields > Add field and choose and search for the required field, repeating this process for each header required.
At Fields, you can rename the default field keynames as required. You can also add up to 10 additional fields to include in each payload. Read more about webhook fields.
To test that your new webhook can communicate and work with the 3rd-party application, click Test. If you receive an unexpected error, go back to double-check your configuration options (above).
Click Create and your new webhook appears as a new data source on the Data sources page.

NOTE: In the Fields section of the API Setup page, there are several mandatory fields which Ortto sends in its request body payload (indicated with padlock icons) that cannot be removed.

Webhook fields

The default (locked) fields included in each webhook payload are described in the table below.

In addition to the default fields, you can send data for up to 10 additional person and organization fields. You can do this when setting up a new webhook or when managing an existing webhook. To do so:

At Fields, click Add field (new webhook) or Edit > Add field (existing webhook).
Select an existing field (or create a new one), then click OK.
Click Create or Done to finish.

NOTE: If a person does not have a value for one of the additional fields to be sent in the webhook payload, that field will be excluded from the payload.

Field (key)	Description
contact_id	The unique identifier for the contact associated with the payload data.
email	The contact’s email address.
campaign_id	The `campaign_id` and `campaign_name` fields identify the campaign the payload was sent from. For example: `campaign_id: "63689f24d42800602c943ec0", campaign_name: "Welcome new subscribers",` The `campaign_id` can be found in the URL of the campaign when you view it. These fields will appear in a webhook payload initiated from a webhook action in a journey or playbook. You won’t see these fields in a payload sent from a campaign-related activity (e.g. Sent email) to a data destination.
campaign_name
action_id	The `action_id` and `action_name` fields identify the playbook action that sent the webhook payload. For example: `action_id: "0064db16ceba37b90dd87c7b", action_name: <webhook name>,` The `action_id` can be found in the URL of the action when you view it. The `action_name` is the name of the webhook the payload is sent to.
action_name

Webhook response statuses

A webhook request will be considered successful if Ortto receives an HTTP response status code in the range of 200 to 399.

Unsuccessful request responses with one of the following codes will not be retried:

400 — bad request
401 — unauthorized
403 — forbidden
404 — not found
405 — method not allowed.

Any unsuccessful response codes within the 400 to 599 range (not included in the preceding list) will be retried up to 12 times. Each retry will have a growing timeout between tries, progressing from 5 minutes to 15 minutes, 1 hour, 5 hours then 1 day between the remaining tries.

Webhook payload data

You can view activity data sent via the webhook, including the HTTP response code and payload data in JSON format, on the webhook data source page, under the Logs tab.

As an example, here is a portion of a webhook payload for a Sent email activity (act::s):

json
 {
  "activity": {
    "id": "<value>",
    "field_id": "act::s",
    "created": "2023-01-16T23:40:54Z",
    "attr": {
      //...
      // Other activity attributes...
      "idt::c": "<value>",
      "idt::ei": "<value>",
      "idt::jri": "<value>",
      "idt::mi": "<value>",
      "str::asn": "Product review survey reminder",
      "str::cn": "Product review survey",
      "str::ct": "journey",
      "str::jsi": "1",
      "str::s": "Hey, we'd love your feedback!"
    }
  },
  "contact": {
      //...
      // Other activity attributes...
  },
  "id": "<value>",
  "time": "2023-01-16T23:41:18.948713601Z",
  "webhook_id": "<value>"
}

Activity attribute field IDs

Activity attribute field data are identified using Ortto’s field IDs (e.g. idt::c). Expand the sections below to find descriptions of the field IDs for common Ortto system activity attributes.

TIP: For activities attributes not listed on this page, such as those for data source activities, you can view the attribute IDs in the Developer section of the relevant activity.

To do so, from the Activities page, click on the activity you want to view. Then in the activity’s view, click Developer to see the attributes.

The field IDs begin with an abbreviation indicating the data type. These are described as follows:

Field type abbreviation	Type of value
idt	Text
str	String (text)
sst	Array (list)
u4s	Array (list)
bol	Boolean (`true`/`false`)
int	Integer. For internal operations and calculations, the Ortto API treats decimal values as integers multiplied by 1,000. This is done to preserve the precision of values resulting from these calculations.
tme	Time and date in UTC format

For a list of common Ortto system activity IDs, see the sections further below.

Default campaign activity attributes

The default campaign-related activity attributes are listed here.

Field ID	Description
idt::a	Audience ID
idt::c	Campaign ID
idt::ei	Asset ID
idt::jri	Journey run ID This identifies the specific entry in the journey. So if a journey can be entered multiple times, you can tell the difference between each entry.
idt::mi	Message ID
sst::t	Attribute tags
str::am	Attribution model
str::an	Audience name
str::asn	Asset name or Email name (depending on activity context)
str::br	Bounced reason
str::burl	Base URL
str::bt	Bounced type
str::c	URL clicked
str::cn	Campaign name
str::ct	Campaign type
str::cvt	Campaign variant type
str::es	Email status
str::fe	Forwarded email
str::jeai	Journey enter activity ID
str::jefi	Journey enter field ID
str::jri	Journey run ID. This identifies the specific entry in the journey. So if a journey can be entered multiple times, you can tell the difference between each entry.
str::jsi	Journey shape ID
str::js	Journey shape log
str::jst	Journey shape title
str::pplt	Push platform
str::pr	Left reason
str::rr	Reaction reason
str::rt	Reaction type or Attributed campaign type (depending on activity context)
str::s	Email subject
str::sc	SMS credits
str::scf	SMS content feedback
str::scr	SMS content response
str::sfn	SMS from number
str::sg	SMS segments
str::sr	Skipped reason or SMS response (depending on activity context)
str::srt	SMS reply trigger
str::uc	UTM campaign content
str::us	UTM campaign source
str::um	UTM campaign medium
str::un	UTM campaign name
str::urlt	URL clicked type
str::ut	UTM campaign term
u4s::t	Tag IDs

Push activity attributes

Attributes for push-related activities are listed here.

Additional campaign-related activity attributes may also be included in push activity payloads, and these are listed under Default campaign activity attributes.

Field ID	Description
str::prs	Push response
str::appos	App operating system (OS)
str::appov	App OS version
str::appn	App name
str::appv	App version
str::sdkv	SDK version

Ad activity attributes

Attributes for ad-related activities are listed here.

Additional campaign-related activity attributes may also be included in ad activity payloads, and these are listed under Default campaign activity attributes.

Field ID	Description
str::aclid	Ad click ID
str::adsrc	Ad source
str::aclkurl	Ad click URL
str::acname	Ad campaign
str::agname	Ad group name
str::aclkus	Ad click UTM source
str::aclkun	Ad click UTM campaign
str::aclkum	Ad click UTM medium
str::aclkuc	Ad click UTM content
str::aclkut	Ad click UTM term
bol::aa	Ad anonymous user

Playbook action attributes

Attributes for playbook-related activities are listed here.

Additional campaign-related activity attributes may also be included in playbook activity payloads, and these are listed under Default campaign activity attributes.

Field ID	Description
str::at	Display title action ID
idt::pa	Action ID
str::pan	Action name
str::pat	Action type
str::patn	Action target name
str::pal	Action log message

Unsubscribe activity attributes

Attributes for unsubscribe-related activities are listed here.

Additional campaign-related activity attributes may also be included in unsubscribe activity payloads, and these are listed under Default campaign activity attributes.

Field ID	Description
str::mrn	Message data missing reason
str::rn	Reason
str::rno	Reason (other)

Web session activity attributes

Attributes for the website session activity are listed here.

Additional campaign-related activity attributes may also be included in web session activity payloads, and these are listed under Default campaign activity attributes.

Field ID	Description
int::pv	Pages visited
str::pu	Page URLs
str::pt	Page titles
str::pp	Page paths
str::fu	First page URL
str::lu	Last page URL
str::ft	First page title
str::lt	Last page title
str::fp	First page path
str::lp	Last page path
str::r	Referrer
bol::a	Anonymous user
str::b	Browser
str::bv	Browser version
str::p	Platform
str::pv	Platform version
str::d	Device
str::l	Language
str:sr	Screen resolution
int:sw	Screen width
int:sh	Screen height
int:sr	Screen pixel ratio
bol:ts	Touch screen

Talk activity attributes

Attributes for Talk activities are listed here.

Field ID	Description
idt::cid	Conversation ID
int::n	Conversation number
str::cts	Conversation subject
str::cst	Conversation status
tme::coa	Conversation opened at
tme::cca	Conversation closed at
tme::cfra	Conversation first response at
int::cfrt	Conversation first response time in minutes
int::cdm	Conversation duration in minutes
int::nor	Conversation number of replies
int::noe	Conversation number of exchanges
bol::cvc	Conversation voice call
bol::cass	Conversation agent screen share
bol::cuss	Conversation user screen share
bol::cs	Conversation secure
int::vcl	Conversation voice call length
int::ssl	Conversation screen share length
tme::csu	Conversation snoozed until
str::csl	Conversation start URL
str::cm	Conversation message
str::ttn	Team name
idt::tid	Team ID
str::can	Conversation assignee name
idt::caid	Conversation assignee ID
str::cmb	Conversation marked by
idt::msb	Conversation marked by ID
str::cch	Conversation channel
str::cie	Conversation inbox email
str::cs	Conversation source
int::crt	Conversation rating
str::crc	Conversation rating comment
str::agn	Agent name
idt::agid	Agent ID
u4s::tids	Conversation tag IDs
sst::tags	Conversation tags

System activity field IDs

This section provides the IDs for common Ortto system activities that you might send to a webhook.

Activities are identified using Ortto’s field IDs (e.g. act::s). Expand the sections below to find descriptions of the field IDs for common Ortto system activities.

Email activities

Field ID	Description
act::s	Sent email
act::c	Clicked email
act::o	Opened email
act::r	Received email
act::b	Bounced email
act::sk	Skipped email
act::rt	Redacted email
act::f	Forwarded email
act::i	Invalid email
act::v	Viewed email online
act::d	Deferred email

SMS activities

Field ID	Description
act::ss	Sent SMS
act::ds	Delivered SMS
act::cs	Clicked SMS
act::is	Invalid SMS
act::bs	Bounced SMS
act::des	Deferred SMS
act::rs	Replied SMS
act::rtss	Responded to SMS survey
act::ras	Rated by survey
act::cos	Confirmation sent via SMS
act::rtns	Responded to NPS
act::sf	Submitted form
act::oos-a	Opted out from SMS audience
act::ois-a	Opted in to SMS audience
act::oos-all	Opted out from all SMS
act::ros-all	Opted in to all SMS
act::ss-ab	SMS subscription abuse
act::scr	SMS consent requested
act::scf	SMS consent failed

Push activities

Field ID	Description
act::sph	Sent push
act::dph	Delivered push
act::cph	Clicked push
act::iph	Invalid push
act::oiip-all	Opted in to all iOS push
act::ooip-all	Opted out of all iOS push
act::oiip-a	Opted in to iOS push audience
act::oips-a	Opted out of iOS push audience
act::oigp-all	Opted in to all Android push
act::oogp-all	Opted out of all Android push
act::oigp-a	Opted out of Android push audience
act::oogs-a	Opted in to Android push audience
act::oiwp-all	Opted in to all web push
act::oowp-all	Opted out of all web push
act::oiwp-a	Opted in to web push audience
act::oows-a	Opted out of to web push audience
act::iws-ab	Web push subscription abuse

Web and user session activities

Field ID	Description
act::ws	Website session
act::us	User session

Audience and tag activities

Field ID	Description
act::enter-audience	Entered audience
act::leave-audience	Left audience
act::ta	Tag added
act::tr	Tag removed
act::u-a	Unsubscribe from audience
act::s-a	Subscribe to audience
act::u-all	Un subscribe from all email
act::s-all	Resubscribe globally
act::s-ab	Subscription abuse

Playbook activities

Field ID	Description
act::ep	Entered playbook
act::lp	Left playbook
act::spa	Successful playbook action
act::fpa	Failed playbook action

Journey activities

Field ID	Description
act::ej	Entered journey
act::lj	Left journey
act::sja	Successful journey action
act::fja	Failed journey action

Field ID	Description
act::cw	Clicked widget
act::sw	Shown widget
act::dw	Dismissed widget
act::rw	Reacted to widget
act::swf	Submitted widget form
act::rws	Responded to widget survey
act::wwv	Watched widget video
act::sww	Spun widget wheel

Talk conversation activities

Field ID	Description
act::cop	Conversation opened
act::cro	Conversation re-opened
act::cas	Conversation assigned
act::clc	Conversation closed
act::csn	Conversation snoozed
act::crt	Conversation rated
act::cms	Conversation marked as spam
act::cvs	Conversation voice call started
act::cve	Conversation voice call ended
act::ctg	Conversation tagged
act::cut	Conversation un-tagged

Configuring a webhook

Create your webhook

Webhook fields

Webhook response statuses

Webhook payload data

Activity attribute field IDs

Default campaign activity attributes

Push activity attributes

Ad activity attributes

Playbook action attributes

Unsubscribe activity attributes

Web session activity attributes

Talk activity attributes

System activity field IDs

Email activities

SMS activities

Push activities

Web and user session activities

Audience and tag activities

Playbook activities

Journey activities

Capture widget activities

Talk conversation activities