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:

  1. Navigate to the Data sources page, then click New data source.
  2. On the Connect a data source page, select All data sources > Webhook (advanced). (Or use the search bar to look for "webhook".)
  3. 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".
  4. 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.
  5. 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.
  6. 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).
  7. 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:

  1. At Fields, click Add field (new webhook) or Edit > Add field (existing webhook).
  2. Select an existing field (or create a new one), then click OK.
  3. 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

Capture widget activities

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