---
title: "Configure webhook"
method: POST
path: "/v1/account/settings/update/webhook_endpoint"
tags: ["Webhooks"]
---

# Configure webhook

`POST /v1/account/settings/update/webhook_endpoint`

## Request

- Base URL: `https://api.ocrolus.com`
- URL: `https://api.ocrolus.com/v1/account/settings/update/webhook_endpoint`
- Auth: OAuth 2
  - Client credentials
  - Token URL: `https://auth.ocrolus.com/oauth/token`

Set up a webhook for your account so your application can react to Ocrolus events.

---
You can find a list of supported account-level event types and their sample notifications in the [Account-level webhook guide](doc:account-level-webhook#available-events).

> 📘 
> Your webhook integration should respond to incoming notifications with a status of `200 OK` to indicate that it's working properly.

> 🚧 We have a better version!
> This product is superseded by [Org Level Webhooks](doc:organization-level-webhook), which we recommend for improved functionality and integration.

## Request body `multipart/form-data`

- object
  - `webhook_endpoint` string, url, required: The URL of the endpoint that will receive notifications of Ocrolus events. This should be on your own infrastructure, protected from the outside world on a network level. See [here](doc:allowlist-of-ip-addresses) for a list of IP addresses that you can add to your firewall's allowlist. The domain will be checked for validity, although the webhook itself won't be called. We suggest [testing the endpoint](ref:test-webhook) after configuring it.
  - `event` WebhookEventType[]: A comma-separated list of events that will trigger a call to your webhook. To deregister the webhook, provide an empty array. The event list given in this parameter will replace all existing subscriptions, i.e. providing a single event will subscribe *only* to that event while unsubscribing from the others.

## Response `200`

Success

- object
  - `status` integer, required: Numerical code indicating the status of this request. Will be 200 for a successful response.
  - `code` integer: Numerical code indicating the nature of an error. Will not be present if the response is successful.
  - `message` string, required: A textual description that indicates details about this response's status. Will be "OK" for a successful request.
  - `response` WebhookRegistration, required: An object that describes the active webhook registration. Only one webhook can be registered at this time; if you need multiple event handlers, your implementation should inspect the request payload and direct events as needed.
    - `webhook_endpoint` string, url, required: The value of `webhook_endpoint` that was provided in the request. Can contain query parameters, port numbers, authentication credentials, and other URL components.
    - `events` WebhookEventType[], required: The webhook events that were successfully registered. Invalid event names will not be included here.

## Other responses

- `400`: Client Errors

---

[API](https://skmtc.dev/ocrolus/apis/account-level-webhooks.md) - [All operations](https://skmtc.dev/ocrolus/apis/account-level-webhooks/llms.txt) - [OpenAPI document](https://skmtc.dev/ocrolus/apis/account-level-webhooks/revisions/aafc604fdd8a?raw)