> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.withpersona.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.withpersona.com/_mcp/server.

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

![webhook-allowlists-relationships](https://assets.withpersona.com/f_auto,q_auto/developer-docs/images/webhook-related-objects-1.png)![webhook-allowlists-relationships](https://assets.withpersona.com/f_auto,q_auto/developer-docs/images/webhook-related-objects-2.png)

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

![webhook-allowlists-relationships](https://assets.withpersona.com/f_auto,q_auto/developer-docs/images/webhook-related-objects-3.png)

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:

**`json`**

```json json
{
  "included": [
    {
      "type": "document/government-id",
      "id": "doc_qoULBi53y2JnxP67epzZv628FSYo",
      "attributes": { "..." : "..." },
      "relationships": { "..." : "..." }
    },
    {
      "type": "report",
      "id": "report_Abc123",
      "attributes": { "..." : "..." },
      "relationships": { "..." : "..." }
    },
    {
      "type": "selfie",
      "id": "selfie_XyZ789",
      "attributes": { "..." : "..." },
      "relationships": { "..." : "..." }
    }
  ]
}
```

### Configuring via the API

Related objects can also be configured programmatically when you [create](/api-reference/webhooks/create-a-webhook) or [update](/api-reference/webhooks/update-a-webhook) 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.

**`Custom`**

```json Custom
{
  "data": {
    "attributes": {
      "included-allowlist": {
        "state": "custom",
        "event-types": [
          { "event-type": "inquiry", "relationships": ["verifications", "documents"] },
          { "event-type": "verification", "relationships": ["*"] }
        ]
      }
    }
  }
}
```

**`Include all`**

```json Include all
{
  "data": {
    "attributes": {
      "included-allowlist": { "state": "include_all" }
    }
  }
}
```

> **Info**
>
> #### Configuration stays in sync with your enabled events
>
> You can only configure event types that the Webhook is subscribed to via `enabled-events` – entries for other event types are dropped when the Webhook is saved. A `custom` configuration whose event types all include every related object (`["*"]`) is equivalent to, and is stored as, `include_all`. The API response reflects the stored configuration, listing only the event types that include related objects.

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

![webhook-allowlists-relationships](https://assets.withpersona.com/f_auto,q_auto/developer-docs/images/webhook-related-objects-4.png)

### Example

Let's say you get the following information from a Webhook with the `inquiry.approved` [Event](/events) enabled:

**`json`**

```json json
{
  "data": {
    "type": "event",
    "id": "evt_XGuYWp7WuDzNxie5z16s7sGJ",
    "attributes": {
      "name": "inquiry.approved",
      "payload": {
        "data": {
          "type": "inquiry",
          "id": "inq_XN8jxMoEhUeihzNypSaFKFfo",
          "attributes": {
            "status": "approved",
            "fields": {
              "birthdate": {
                "type": "date",
                "value": "1977-07-17"
              },
              "name-last": {
                "type": "string",
                "value": "Sample"
              },
              "name-first": {
                "type": "string",
                "value": "Alexander"
              }
            }
          },
          "relationships": {
            "account": {
              "data": {
                "type": "account",
                "id": "act_ABC123"
              }
            },
            "template": {
              "data": {
                "type": "template",
                "id": "tmpl_XYZ789"
              }
            }
          }
        }
      }
    }
  }
}
```

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

![webhook-allowlists-relationships](https://assets.withpersona.com/f_auto,q_auto/developer-docs/images/webhook-related-objects-5.png)

The new payload would look like this:

**`json`**

```json json
{
  "data": {
    "type": "event",
    "id": "evt_XGuYWp7WuDzNxie5z16s7sGJ",
    "attributes": {
      "name": "inquiry.approved",
      "payload": {
        "data": {
          "type": "inquiry",
          "id": "inq_XN8jxMoEhUeihzNypSaFKFfo",
          "attributes": {
            "status": "approved",
            "fields": {
              "birthdate": {
                "type": "date",
                "value": "1977-07-17"
              },
              "name-last": {
                "type": "string",
                "value": "Sample"
              },
              "name-first": {
                "type": "string",
                "value": "Alexander"
              }
            }
          }
        }
      }
    }
  }
}
```