Webhook Allowlists

Use allowlists to control what types of information your webhooks include. View and edit your webhooks’ allowlists on each Webhook’s Payload Configuration tab.

Related Objects

Configure which related objects are returned in your Webhook Events’ included array. By default, Webhook Event payloads do not include any related objects. You can configure which related objects to return for each event type. For example, if your Webhook includes account.created and inquiry.completed events – you will be able to configure which related objects are returned separately for your Account events and Inquiry events.

Example

The top-level section corresponds to each event type enabled for the Webhook. For example, if your Webhook has the inquiry.completed event enabled – you will see an “Inquiry Webhooks” section. This will let you configure which related objects are included with your Inquiry events on the Webhook. You can enable or disable all related objects for a given Event type in bulk, or you can configure individual related objects.

From the screenshot above – this configuration would only include document, reports, and selfie related objects for Inquiry Events. This means that an inquiry.approved event could have the following payload in 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
}

Configuring via the API

Related objects can also be configured programmatically when you create or update a Webhook, using the included-allowlist attribute. This mirrors the Related Objects configuration in the Dashboard.

Set state to one of:

• include_all – include every related object for all of the Webhook’s event types.
• include_none – include no related objects (the default).
• custom – configure related objects per event type via event-types.

For custom, event-types is an array of { "event-type", "relationships" } entries. Use ["*"] to include every related object for that event type, or list specific relationship names (the two cannot be combined). Event types you omit return no related objects.

1
{
2
  "data": {
3
    "attributes": {
4
      "included-allowlist": {
5
        "state": "custom",
6
        "event-types": [
7
          { "event-type": "inquiry", "relationships": ["verifications", "documents"] },
8
          { "event-type": "verification", "relationships": ["*"] }
9
        ]
10
      }
11
    }
12
  }
13
}

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 using the Relationships toggle.

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
}

To remove those relationships from your Webhook Events, you can disable the Relationships toggle.

The new 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
}