Outbound webhooks

Webhooks notify an external application when events take place in the Pattern platform. This allows applications to take action, such as calling back into the Pattern API for group member or task data. Webhooks are managed in the Pattern administrative console.

Configure a webhook

To configure a webhook for a group:

  1. In your group, on the left navigation bar, select Settings > Integrations > Webhooks

  2. Select Add Webhook

  3. In Name, enter a name for your webhook

  4. In URL, enter the URL of the webhook endpoint. The URL must be encoded if it contains any special characters.

  5. Optional: Disable the SSL Certificate Verfication slider to deactivate SSL Verification. Disabling this setting is useful for testing, but it is strongly recommended to enable in a production setting.

  6. Optional: In Secret token, enter the secret token value that can be used to validate payloads.

  7. In the Trigger section, select the avaiable trigger and choose the task type

  8. Select Save

Configure your webhook receiver endpoint

All webhook endpoints should follow these guidelines:

  • Endpoints should quickly respond with a 200 or 201 status code: Avoid any heavyweight synchronous processing of the webhook request. Long running request-response cycles can lead to duplicate events getting sent.

  • Be prepared to handle duplicate events: In some circumstances, duplicates events can be sent. Be prepared to handle these gracefully.

  • Response bodies should be empty: The Pattern Health platform does not inspect responses back from the receiver endpoint, so we recommend an empty response body and keeping headers lightweight.

Test a webhook

You can trigger any webhook to validate that it working as expected.

To test a webhook:

  1. In your group, on the left navigation bar, select Settings > Integrations > Webhooks

  2. Select Edit on the Webhook you want to test

  3. Under the Test Details section, select the Test button and choose which trigger type you want to test

  4. The request and response details as well as any error details should be displayed just below the Test button

The results of a test are not persisted on the Pattern platform

Validate a webhook payload

A Secret Token specified on a webhook will be sent with the request to the webhook receiver endpoint in the X-PHT-Webhook-Token HTTP request header. Your endpoint can validate the token to ensure the request was legitimate.

Supported triggers

  • Task completion: Task type is configurable.

Hierarchical evaluation of webhooks

Webhooks cascade down the group hierarchy. A webhook trigger that is fired for any given group will match all webhooks in that group as well as any ancestor group. A request will be sent for each matching webhook.