> ## Documentation Index > Fetch the complete documentation index at: https://documentation.debbiecollect.com/llms.txt > Use this file to discover all available pages before exploring further. # Create webhook > Creates a webhook that POSTs the events it is subscribed to. The response carries the verification token sent with every delivery — store it, it is not shown again. **Required scope:** `write:webhooks` ## OpenAPI ````yaml POST /v1/{tenantId}/webhooks openapi: 3.1.0 info: title: Debbie API Docs description: > The Debbie API is a RESTful interface, allowing you to programmatically update, add and access your data in the platform. It provides predictable URLs for accessing resources, and uses built-in HTTP features to receive commands and return responses. This makes it easy to communicate with third party systems. ## Idempotency The Debbie API supports idempotency for non-idempotent requests through the optional `Idempotency-Key` header. This ensures that retrying the same request multiple times will produce the same result, preventing duplicate operations. ### Using Idempotency Keys - Include an `Idempotency-Key` header with a unique string (we recommend UUIDs) - Maximum key length is 64 characters - Keys are valid for 48 hours - Responses served from the idempotency cache include an `Idempotency-Cached` header ### Example ```http Idempotency-Key: 123e4567-e89b-12d3-a456-426614174000 ``` ### Error Cases - Invalid key format: 400 Bad Request - Reusing a key for a different request: 400 Bad Request ### Best Practices - Use a new key for each unique business transaction - Use the same key when retrying a failed request - Store keys with request details for debugging contact: email: api-support@debbie.dk version: v0.1.0 servers: - url: https://api.debbiecollect.com security: - bearerAuth: [] tags: - name: Authorization description: Endpoints for interacting with authorization - name: Cases description: Endpoints for interacting with cases - name: Customers description: Endpoints for interacting with customers - name: Creditors description: Endpoints for interacting with creditors - name: Ultimate creditors description: >- Endpoints for interacting with ultimate creditors. An ultimate creditor is the original creditor behind the creditor on a case — for example when a debt collection agency forwards cases on behalf of its own client. On cases with an ultimate creditor, the creditor template mentions (name, address and company identifier) use the details of the ultimate creditor. - name: Updates description: Endpoints for interacting with updates - name: Users description: Endpoints for interacting with updates - name: Files description: Endpoints for interacting with files - name: Case vouchers description: Endpoints for interacting with case vouchers - name: Voucher types description: The voucher types of the tenant, used to categorize case vouchers - name: Interactions description: >- Interactions are messages and notes on a case, for example an incoming message from a debtor. - name: Billing description: Endpoints for interacting with billing - name: Transaction accounts description: >- Endpoints for interacting with transaction accounts — the bank and payment service provider accounts that payments are registered on - name: Links description: Endpoints for generating links - name: Webhooks description: >- Debbie provides a range of webhooks. To try them out please visit Debbie Caseworker and navigate to Settings --> Developers --> Webhooks. - name: End reasons description: Endpoints for interacting with end reasons - name: Case groups description: Endpoints for interacting with case groups externalDocs: description: Find out more about Debbie here url: https://debbiecollect.com paths: /v1/{tenantId}/webhooks: post: tags: - Webhooks summary: Create webhook description: >- Creates a webhook that POSTs the events it is subscribed to. The response carries the verification token sent with every delivery — store it, it is not shown again. **Required scope:** `write:webhooks` operationId: create-webhook parameters: - in: path name: tenantId schema: type: string format: uuid required: true description: Id of the tenant requestBody: required: true content: application/json: schema: type: object properties: name: type: string description: >- Name of the webhook. Shown in the portal and on every delivery. url: type: string format: uri description: >- Public HTTP(S) address every delivery is POSTed to. Addresses on a private network are rejected. events: type: array items: type: string minItems: 1 description: >- Events to subscribe to, for example cases.create. Every event in the Webhooks reference can be subscribed to. email: type: - string - 'null' format: email description: Address notified when deliveries keep failing. headers: type: - object - 'null' additionalProperties: type: string description: >- Extra headers sent with every delivery, for example an authorization header the receiver expects. deepFlattenBody: type: boolean description: >- Flatten nested objects in the body into single level keys joined by "_", for receivers that cannot read nested JSON. Defaults to false. pull: type: boolean description: >- Hold deliveries for the webhook items endpoints instead of POSTing them. Defaults to false. creditorId: type: - string - 'null' format: uuid description: >- Scope the webhook to one creditor, so it only receives events for that creditor. Omit it for a tenant wide webhook. required: - name - url - events example: name: ERP sync url: https://example.com/debbie/webhooks events: - cases.create - cases.update - updates.create email: integrations@example.com responses: '200': description: Successful operation content: application/json: schema: $ref: '#/components/schemas/Webhook' '401': $ref: '#/components/responses/UnauthorizedError' '422': $ref: '#/components/responses/UnprocessableContent' components: schemas: Webhook: type: object properties: id: type: string format: uuid description: Id of the webhook name: type: string description: Name of the webhook url: type: string format: uri description: Address every delivery is POSTed to events: type: array items: type: string description: Events the webhook is subscribed to creditorId: type: - string - 'null' format: uuid description: >- Id of the creditor the webhook is scoped to. null is a tenant wide webhook that receives events for every creditor. verificationToken: type: string format: uuid description: >- Sent as the X-Verification-Token header on every delivery. Compare it with this value and reject requests that do not match. email: type: - string - 'null' format: email description: >- Address notified when deliveries keep failing. null when no address was given. headers: type: - object - 'null' additionalProperties: type: string description: Extra headers sent with every delivery bodyMappers: type: - object - 'null' description: >- Per event field maps that reshape the body before it is sent. null when the body is sent as it is. deepFlattenBody: type: boolean description: >- Whether nested objects in the body are flattened into single level keys joined by "_" pull: type: boolean description: >- Whether deliveries wait to be pulled through the webhook items endpoints instead of being POSTed enabled: type: boolean description: Whether the webhook is receiving events createdAt: type: string format: date-time description: When the webhook was created createdBy: type: - object - 'null' description: Who created the webhook properties: id: type: string description: Id of the actor type: type: string description: Type of the actor example: id: b963f219-255e-47b7-a3f2-0fe6180514a1 name: ERP sync url: https://example.com/debbie/webhooks events: - cases.create - cases.update creditorId: null verificationToken: 5f2e6a55-6f7d-4d0e-8f1c-2f5a2f8d7c11 email: integrations@example.com headers: X-Custom: value deepFlattenBody: false pull: false enabled: true createdAt: '2026-08-29T11:21:10.100Z' createdBy: id: b1a2c3d4-e5f6-7a8b-9c0d-1e2f3a4b5c6d type: KEY bodyMappers: null responses: UnauthorizedError: description: Access token missing or invalid UnprocessableContent: description: Unable to process the contained instructions. securitySchemes: bearerAuth: type: http scheme: bearer description: >- Authentication can be done by using a bearer token in the Authorization header. This is done using the following format `Authorization: Bearer {token}`. ````