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

Assuming you initially followed the Configuring a new data source procedure, use this procedure to complete configuring your webhook to work with your relevant Ortto account’s action from a playbook campaign, journey campaign, or activity.

  1. After having clicked through Popular  Webhook (advanced)  Get started (from the New data source page), on the Setup page, complete the following fields:

    • Webhook name - the name of this particular webhook configuration, as it will appear on the Data sources page.

    • 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.

  2. 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.

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

  3. 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).

  4. Click Create and your new webhook appears as a new data source on the Data sources page.

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.