--- title: "Update a Webhook" method: PATCH path: "/webhooks/{webhook-id}" tags: ["webhooks"] --- # Update a Webhook `PATCH /webhooks/{webhook-id}` ## Request - Base URL: `https://api.withpersona.com/api/v1` - URL: `https://api.withpersona.com/api/v1/webhooks/{webhook-id}` - Auth: HTTP bearer Updates an existing Webhook. ## Path parameters - `webhook-id` string, required ## Query parameters - `include` string - `fields` object ## Headers - `Key-Inflection` 'camel' | 'kebab' | 'snake' - `Idempotency-Key` string - `Persona-Version` '2026-09-29' | '2025-12-08' | '2025-10-27' | '2023-01-05' | '2022-09-01' | '2021-08-18' | '2021-07-05' | '2021-02-21' | '2020-05-18': Server API version. More info on versioning can be found [here](https://docs.withpersona.com/versioning). ## Request body - object - `data` WebhooksWebhookIdPatchRequestBodyContentApplicationJsonSchemaData - `attributes` WebhookRequestAttributes - `name` string, nullable: A name for remembering webhook - `description` string, nullable: An optional description for this webhook - `url` string: URL to which webhook events are forwarded. - `enabled-events` WebhookRequestAttributesEnabledEventsItems[]: Supported events that you want to receive webhooks for. Set `*` to enable all events. Descriptions of all events can be found [here](https://docs.withpersona.com/events). Retrieve Events for your organization using the [Events API](https://docs.withpersona.com/api-reference/events/list-all-events). Custom events you emit yourself may also be subscribed to by name. - union - '*' | 'account-property.redacted' | 'account-type.deleted-field' | 'account.added-relation' | 'account.archived' | 'account.consolidated' | 'account.consolidated-with' | 'account.created' | 'account.redacted' | 'account.removed-relation' | 'account.restored' | 'account.status-updated' | 'account.tag-added' | 'account.tag-removed' | 'account.updated-fields' | 'account.updated-tags' | 'agent-conversation.created' | 'agent-conversation.errored' | 'agent-conversation.message-added' | 'authentication-template.authentication-errored' | 'authentication.completed' | 'authentication.created' | 'authentication.expired' | 'authentication.failed' | 'authentication.redacted' | 'batch-job.canceled' | 'batch-job.completed' | 'batch-job.errored' | 'batch-job.paused' | 'batch-job.resumed' | 'batch-job.started' | 'case-comment.created' | 'case-message.received' | 'case-message.sent' | 'case-template.deleted-field' | 'case.assigned' | 'case.created' | 'case.exported' | 'case.print-initiated' | 'case.queue-updated' | 'case.redacted' | 'case.reopened' | 'case.resolved' | 'case.sla-expired' | 'case.status-updated' | 'case.updated' | 'case.updated-fields' | 'case.updated-tags' | 'checkpoint.completed' | 'checkpoint.created' | 'checkpoint.expired' | 'checkpoint.failed' | 'checkpoint.reusable-persona-used' | 'checkpoint.started' | 'connect/share-token.inbound-created' | 'connect/share-token.inbound-redeemed' | 'connect/share-token.outbound-created' | 'connect/share-token.outbound-redeemed' | 'deployment.completed' | 'document.created' | 'document.errored' | 'document.extracted' | 'document.pending' | 'document.processed' | 'document.submitted' | 'filing.created' | 'filing.filed' | 'graph-query.cancelled' | 'graph-query.completed' | 'graph-query.errored' | 'graph-query.reran' | 'graph-query.submitted' | 'graph-query.timed-out' | 'importer-pipeline-run.canceled' | 'importer-pipeline-run.completed' | 'importer-pipeline-run.errored' | 'importer-pipeline-run.paused' | 'importer-pipeline-run.resumed' | 'importer-pipeline-run.started' | 'inquiry-session.canceled' | 'inquiry-session.expired' | 'inquiry-session.started' | 'inquiry-template-version.created' | 'inquiry-template-version.published' | 'inquiry.approved' | 'inquiry.completed' | 'inquiry.created' | 'inquiry.declined' | 'inquiry.expired' | 'inquiry.failed' | 'inquiry.marked-for-review' | 'inquiry.redacted' | 'inquiry.reusable-persona-assurance-failed' | 'inquiry.reusable-persona-created' | 'inquiry.reusable-persona-updated' | 'inquiry.reusable-persona-used' | 'inquiry.started' | 'inquiry.transitioned' | 'inquiry.updated-tags' | 'integration-log.created' | 'report/address-lookup.errored' | 'report/address-lookup.ready' | 'report/address-lookup.submitted' | 'report/adverse-media.dismissed' | 'report/adverse-media.errored' | 'report/adverse-media.matched' | 'report/adverse-media.ready' | 'report/background-check.ready' | 'report/better-business-bureau.errored' | 'report/better-business-bureau.ready' | 'report/business-adverse-media.dismissed' | 'report/business-adverse-media.errored' | 'report/business-adverse-media.matched' | 'report/business-adverse-media.ready' | 'report/business-associated-persons.errored' | 'report/business-associated-persons.ready' | 'report/business-classification.errored' | 'report/business-classification.ready' | 'report/business-classification.submitted' | 'report/business-enforcement-action.errored' | 'report/business-enforcement-action.ready' | 'report/business-enforcement-action.submitted' | 'report/business-industry-classification.errored' | 'report/business-industry-classification.ready' | 'report/business-industry-classification.submitted' | 'report/business-liens-lookup.errored' | 'report/business-liens-lookup.ready' | 'report/business-lookup-eu.errored' | 'report/business-lookup-eu.ready' | 'report/business-lookup.errored' | 'report/business-lookup.ready' | 'report/business-media-coverage.errored' | 'report/business-media-coverage.matched' | 'report/business-media-coverage.ready' | 'report/business-media-coverage.submitted' | 'report/business-nonprofit.changed' | 'report/business-nonprofit.errored' | 'report/business-nonprofit.ready' | 'report/business-online-presence.errored' | 'report/business-online-presence.ready' | 'report/business-online-presence.submitted' | 'report/business-personnel-insights.errored' | 'report/business-personnel-insights.ready' | 'report/business-personnel-insights.submitted' | 'report/business-registrations-lookup.errored' | 'report/business-registrations-lookup.ready' | 'report/business-social-media.errored' | 'report/business-social-media.ready' | 'report/business-watchlist.dismissed' | 'report/business-watchlist.errored' | 'report/business-watchlist.matched' | 'report/business-watchlist.ready' | 'report/business-website.errored' | 'report/business-website.ready' | 'report/chainalysis-address-screening.errored' | 'report/chainalysis-address-screening.ready' | 'report/clearbit-business-lookup.errored' | 'report/clearbit-business-lookup.ready' | 'report/coinbase-check-crypto-risk.errored' | 'report/coinbase-check-crypto-risk.ready' | 'report/community-safety.errored' | 'report/community-safety.matched' | 'report/community-safety.ready' | 'report/comply-advantage-search.ready' | 'report/comprehensive-profile.ready' | 'report/crypto-address-watchlist.errored' | 'report/crypto-address-watchlist.matched' | 'report/crypto-address-watchlist.ready' | 'report/crypto_address.matched' | 'report/crypto_address.ready' | 'report/custom-list.dismissed' | 'report/custom-list.errored' | 'report/custom-list.matched' | 'report/custom-list.ready' | 'report/email-address.errored' | 'report/email-address.ready' | 'report/employer-lookup.ready' | 'report/equifax-oneview.errored' | 'report/equifax-oneview.ready' | 'report/finra-broker-check.errored' | 'report/finra-broker-check.ready' | 'report/kyckr-business-lookup.errored' | 'report/kyckr-business-lookup.ready' | 'report/middesk.errored' | 'report/middesk.ready' | 'report/middesk.submitted' | 'report/mx-account.errored' | 'report/mx-account.ready' | 'report/nces.errored' | 'report/nces.ready' | 'report/novacredit-cash-atlas.errored' | 'report/novacredit-cash-atlas.ready' | 'report/novacredit-cash-atlas.submitted' | 'report/novacredit-credit-passport.errored' | 'report/novacredit-credit-passport.ready' | 'report/novacredit-credit-passport.submitted' | 'report/phone-number.errored' | 'report/phone-number.ready' | 'report/politically-exposed-person.dismissed' | 'report/politically-exposed-person.errored' | 'report/politically-exposed-person.matched' | 'report/politically-exposed-person.ready' | 'report/profile-non-authoritative.errored' | 'report/profile-non-authoritative.ready' | 'report/profile.errored' | 'report/profile.ready' | 'report/screening.errored' | 'report/screening.matched' | 'report/screening.ready' | 'report/screening.reviewed' | 'report/sec-action-lookup.errored' | 'report/sec-action-lookup.ready' | 'report/sentilink-application-risk.errored' | 'report/sentilink-application-risk.ready' | 'report/sentilink-scores.errored' | 'report/sentilink-scores.ready' | 'report/social-media.errored' | 'report/social-media.ready' | 'report/synthetic.errored' | 'report/synthetic.ready' | 'report/trm-wallet-screening.errored' | 'report/trm-wallet-screening.ready' | 'report/watchlist.dismissed' | 'report/watchlist.errored' | 'report/watchlist.matched' | 'report/watchlist.ready' | 'sar.created' | 'sar.filed' | 'selfie.created' | 'selfie.errored' | 'selfie.processed' | 'selfie.submitted' | 'session.created' | 'session.expired' | 'transaction-type.deleted-field' | 'transaction.added-relation' | 'transaction.created' | 'transaction.labeled' | 'transaction.redacted' | 'transaction.removed-relation' | 'transaction.sentinel-session-processed' | 'transaction.status-updated' | 'transaction.updated-fields' | 'user.availability-updated' | 'verification.canceled' | 'verification.created' | 'verification.escalated' | 'verification.failed' | 'verification.passed' | 'verification.requires-retry' | 'verification.skipped' | 'verification.submitted' | 'verification.tentatively-failed' | 'verification.tentatively-passed' | 'verification.updated-tags' | 'workflow-run.completed' | 'workflow-run.created' | 'workflow-run.errored' | 'workflow-run.resumed' | 'workflow.published' - string - `api-version` '2026-09-29' | '2025-12-08' | '2025-10-27' | '2023-01-05' | '2022-09-01' | '2021-08-18' | '2021-07-05' | '2021-02-21' | '2020-05-18': Server API version. More info on versioning can be found [here](https://docs.withpersona.com/versioning). - `api-key-inflection` 'camel' | 'kebab' | 'snake': Default key inflection for attribute keys in incoming webhook requests. For more info see the [Key Inflection docs](https://docs.withpersona.com/key-inflection). - `api-attributes-blocklist` string[]: Attributes blocked from webhook requests. For more info see [Webhook Attributes Blocklist](https://docs.withpersona.com/webhook-blocklists#attribute-blocklist). - `file-access-token-expires-in` integer: How soon any file access tokens in webhook requests expire. For more info see [Downloading Files](https://docs.withpersona.com/downloading-files). - `payload-filter` WebhookRequestAttributesPayloadFilter: Filter webhook events based on payload data. Only available for enterprise clients. For more info see [Webhook Event Filters](https://docs.withpersona.com/webhook-event-filters). - `data` object - `included-allowlist` union: Controls which related objects appear in the `included` array of webhook payloads. The default is `include_none`. When `state` is `custom`, `event-types` configures which related objects to include per event type: event types you are subscribed to (via `enabled-events`) but do not list are excluded, and event types you list but are not subscribed to are dropped on save. A `custom` config whose event types are all `["*"]` is equivalent to, and is normalized to, `include_all`. - IncludedAllowlist0 - `state` 'include_all', required: Include all related objects for every subscribed event type. - IncludedAllowlist1 - `state` 'include_none', required: Include no related objects (the default). - IncludedAllowlist2 - `state` 'custom', required: Configure included related objects per event type via `event-types`. - `event-types` IncludedAllowlistOneOf2EventTypesItems[], required: Per-event-type include configuration. At most one entry per event type. - `event-type` string, required: Event type identifier (e.g. `inquiry`, `account`). - `relationships` string[], required: Related object names to include for this event type, or `["*"]` to include all related objects. `"*"` cannot be combined with named relationships. - `relationship-allowlist` union: Controls whether relationships are serialized in webhook payload objects. The default is `include_all`. The object shape leaves room for future granular relationship configuration. - RelationshipAllowlist0 - `state` 'include_all', required: Include relationship linkages in webhook payload objects. - RelationshipAllowlist1 - `state` 'include_none', required: Omit relationship linkages from webhook payload objects. - `custom-http-headers` WebhookRequestAttributesCustomHttpHeaders: Custom HTTP headers to include in webhook requests. For more info see [Webhook Custom HTTP Headers](https://docs.withpersona.com/webhook-custom-http-headers). - `Authorization` string - `Calling-Application` string - `CF-Access-Client-Id` string - `CF-Access-Client-Secret` string - `X-API-Key` string ## Response `200` This endpoint returns a Webhook object. - WebhooksUpdateAWebhookResponse200 - `data` Webhook, required: A Webhook object - `type` 'webhook' - `id` string - `attributes` WebhookAttributes - `status` string - `url` string - `name` string, nullable - `description` string, nullable - `api-version` '2026-09-29' | '2025-12-08' | '2025-10-27' | '2023-01-05' | '2022-09-01' | '2021-08-18' | '2021-07-05' | '2021-02-21' | '2020-05-18': Server API version. More info on versioning can be found [here](https://docs.withpersona.com/versioning). - `api-key-inflection` string - `api-attributes-blocklist` string[] - `file-access-token-expires-in` integer - `enabled-events` string[] - `payload-filter` WebhookAttributesPayloadFilter - `included-allowlist` union: Controls which related objects appear in the `included` array of webhook payloads. The default is `include_none`. When `state` is `custom`, `event-types` configures which related objects to include per event type: event types you are subscribed to (via `enabled-events`) but do not list are excluded, and event types you list but are not subscribed to are dropped on save. A `custom` config whose event types are all `["*"]` is equivalent to, and is normalized to, `include_all`. - IncludedAllowlist0 - `state` 'include_all', required: Include all related objects for every subscribed event type. - IncludedAllowlist1 - `state` 'include_none', required: Include no related objects (the default). - IncludedAllowlist2 - `state` 'custom', required: Configure included related objects per event type via `event-types`. - `event-types` IncludedAllowlistOneOf2EventTypesItems[], required: Per-event-type include configuration. At most one entry per event type. - `event-type` string, required: Event type identifier (e.g. `inquiry`, `account`). - `relationships` string[], required: Related object names to include for this event type, or `["*"]` to include all related objects. `"*"` cannot be combined with named relationships. - `relationship-allowlist` union: Controls whether relationships are serialized in webhook payload objects. The default is `include_all`. The object shape leaves room for future granular relationship configuration. - RelationshipAllowlist0 - `state` 'include_all', required: Include relationship linkages in webhook payload objects. - RelationshipAllowlist1 - `state` 'include_none', required: Omit relationship linkages from webhook payload objects. - `created-at` string, date-time - `included` unknown[]: Excluded from the response by default. Will be an empty array when the `include` query parameter in the request was explicitly set to empty. - unknown ## Other responses - `400`: The request was unacceptable, often due to invalid parameters. - `401`: An invalid API key was provided. - `403`: The given API key doesn’t have permissions to perform the request or a quota has been exceeded. - `404`: The requested resource doesn’t exist. - `409`: The request conflicts with another request, often due to attempting to create a duplicate resource. - `422`: The request modifies the resource in an unacceptable way, often due to an invalid action or parameter. - `429`: Your organization’s rate limit has been exceeded. We recommend an exponential backoff on requests. ## Changes - **2026-10-23** `effd3bfb74c2`: 1 info - added the new `authentication-template.authentication-errored` enum value to the request property `data/attributes/enabled-events/items/oneOf[subschema #1: WebhookRequestAttributesEnabledEventsItems0]/` - **2026-10-14** `6943c0e307f8`: 1 info - added the new `deployment.completed` enum value to the request property `data/attributes/enabled-events/items/oneOf[subschema #1: WebhookRequestAttributesEnabledEventsItems0]/` [Operation history](https://skmtc.dev/withpersona/apis/withpersona-2/changes/webhooks/:webhook-id/patch.md) --- [API](https://skmtc.dev/withpersona/apis/withpersona-2.md) - [All operations](https://skmtc.dev/withpersona/apis/withpersona-2/llms.txt) - [OpenAPI document](https://skmtc.dev/withpersona/apis/withpersona-2/revisions/f1c78133b3b2?raw)