Webhook Allowlists

If you want to control which information gets sent to your server via webhooks, you can configure allowlists via the Payload Configuration tab. To view and edit allowlist settings, visit your Webhooks page in the Dashboard and click into a particular webhook to view its configuration.

Included Allowlist

The Included Allowlist controls which related objects are present under the included key of the webhook payload. By default, Webhook Event payloads will NOT include the trigger object’s related objects in included. Configuration is per event type. For example, if your webhook is enabled for account.created, case.updated, and inquiry.completed events as so:

Then the Dashboard will display a corresponding Account, Case, and Inquiry Webhooks section in the Payload Configuration tab:

Allowlists allow you to granularly configure which specific objects you want in the included portion of a webhook event payload. Configuration of the allowlist is done by event type, this means that for whichever events your webhook is enabled to trigger on, you can pick specific relationships for the base object (e.g. Inquiry, Report, etc.) to allowlist.

How it works

The top-level checkbox for each webhook section (e.g., Inquiry Webhooks) allows you to include all relationships or none. Each child checkbox corresponding to the relationships for an object lets you handpick which specific relationships you would like to allow in the included payload.

For more information on the structure of payloads, see Serialization.

Example

Let’s say you have a Webhook with the inquiry.approved Event enabled. This would lead to the Inquiry Webhooks section being displayed in the Payload Configuration Tab.

The top-level checkbox for Inquiry Webhooks allows you to include all relationships or none. Each child checkbox corresponding to the relationships for an Inquiry allows you to handpick which specific relationships you would like to allow in the included payload.

This existing configuration would only include document, reports, and selfie objects for Inquiry Events. This means a triggered inquiry.approved event would result in the following payload under the included key:

1
{
2
  "included": [
3
    {
4
      "type": "document/government-id",
5
      "id": "doc_qoULBi53y2JnxP67epzZv628FSYo",
6
      "attributes": { "..." : "..." },
7
      "relationships": { "..." : "..." }
8
    },
9
    {
10
      "type": "report",
11
      "id": "report_Abc123",
12
      "attributes": { "..." : "..." },
13
      "relationships": { "..." : "..." }
14
    },
15
    {
16
      "type": "selfie",
17
      "id": "selfie_XyZ789",
18
      "attributes": { "..." : "..." },
19
      "relationships": { "..." : "..." }
20
    }
21
  ]
22
}

Relationship Allowlist

By default, Webhook Event payloads will include all of the trigger object’s related objects in relationships. You have the option of fully removing all relationships from webhook event payloads by deselecting the checkbox when viewing a webhook in your Dashboard.

Example

Let’s say you get the following information from a Webhook with the inquiry.approved Event enabled:

1
{
2
  "data": {
3
    "type": "event",
4
    "id": "evt_XGuYWp7WuDzNxie5z16s7sGJ",
5
    "attributes": {
6
      "name": "inquiry.approved",
7
      "payload": {
8
        "data": {
9
          "type": "inquiry",
10
          "id": "inq_XN8jxMoEhUeihzNypSaFKFfo",
11
          "attributes": {
12
            "status": "approved",
13
            "fields": {
14
              "birthdate": {
15
                "type": "date",
16
                "value": "1977-07-17"
17
              },
18
              "name-last": {
19
                "type": "string",
20
                "value": "Sample"
21
              },
22
              "name-first": {
23
                "type": "string",
24
                "value": "Alexander"
25
              }
26
            }
27
          },
28
          "relationships": {
29
            "account": {
30
              "data": {
31
                "type": "account",
32
                "id": "act_ABC123"
33
              }
34
            },
35
            "template": {
36
              "data": {
37
                "type": "template",
38
                "id": "tmpl_XYZ789"
39
              }
40
            }
41
          }
42
        }
43
      }
44
    }
45
  }
46
}

If you didn’t want to get any of the data in the relationships object, you could update your relationship allowlist to remove all relationships by deselecting the checkbox on the Payload Configuration screen in Dashboard, as shown above. The resulting payload would look like this:

1
{
2
  "data": {
3
    "type": "event",
4
    "id": "evt_XGuYWp7WuDzNxie5z16s7sGJ",
5
    "attributes": {
6
      "name": "inquiry.approved",
7
      "payload": {
8
        "data": {
9
          "type": "inquiry",
10
          "id": "inq_XN8jxMoEhUeihzNypSaFKFfo",
11
          "attributes": {
12
            "status": "approved",
13
            "fields": {
14
              "birthdate": {
15
                "type": "date",
16
                "value": "1977-07-17"
17
              },
18
              "name-last": {
19
                "type": "string",
20
                "value": "Sample"
21
              },
22
              "name-first": {
23
                "type": "string",
24
                "value": "Alexander"
25
              }
26
            }
27
          }
28
        }
29
      }
30
    }
31
  }
32
}