> ## Documentation Index > Fetch the complete documentation index at: https://docs.paywise.de/llms.txt > Use this file to discover all available pages before exploring further. # Create webhook ## OpenAPI ````yaml /api-docs/partner-api/openapi.json post /partner/v2/webhooks/ openapi: 3.0.3 info: description: >- Onboard and manage companies and their memberships through the current API at the `/partner/v2/` HTTP path. title: paywise Partner API version: current servers: - description: Production environment url: https://api.paywise.de - description: Sandbox environment url: https://api-sandbox.paywise.de security: [] tags: - description: Client companies managed by the partner. name: Companies - description: Memberships and invitations of a managed company. name: Company users - description: Webhook endpoints and their signing secrets. name: Webhooks - description: Delivery log and redelivery of webhook events. name: Webhook deliveries - description: Ordered feed of the events webhooks deliver. name: Events - description: Reference catalog of legal forms. name: Legal forms - description: The authenticated credential and API availability. name: Meta - description: Rate-limit headroom of the credential. name: Usage externalDocs: url: https://docs.paywise.de/api-docs/partner-api/introduction paths: /partner/v2/webhooks/: post: tags: - Webhooks summary: Create webhook operationId: create-webhook parameters: - description: >- Required client-supplied command key scoped to the selected Case company or Partner owner, method, operation and path. An exact retry replays the original response while it is retained, including after credential rotation or replacement. Current permissions are required. in: header name: Idempotency-Key required: true schema: maxLength: 255 type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/PartnerWebhookRequest' required: true responses: '201': content: application/json: schema: $ref: '#/components/schemas/PartnerWebhookWithSecret' description: '' headers: Cache-Control: description: >- Cacheability directive. Authenticated responses use `private, no-store`; the legal-form catalog may use `private, max-age=86400`. schema: type: string X-Paywise-Environment: description: Environment that produced the response. schema: enum: - production - sandbox type: string X-Paywise-Request-Id: description: >- Fresh server-assigned correlation id for this response. Caller-provided request ids are ignored. schema: format: uuid type: string '400': content: application/json: examples: validation-error: value: code: validation_error detail: The request contains invalid data. errors: - code: invalid field: users[0].email message: Enter a valid email address. schema: $ref: '#/components/schemas/Error' description: Standard error response. headers: Cache-Control: description: >- Cacheability directive. Authenticated responses use `private, no-store`; the legal-form catalog may use `private, max-age=86400`. schema: type: string X-Paywise-Environment: description: Environment that produced the response. schema: enum: - production - sandbox type: string X-Paywise-Request-Id: description: >- Fresh server-assigned correlation id for this response. Caller-provided request ids are ignored. schema: format: uuid type: string '401': content: application/json: examples: authentication-error: value: code: not_authenticated detail: Authentication credentials were not provided. schema: $ref: '#/components/schemas/Error' description: Standard error response. headers: Cache-Control: description: >- Cacheability directive. Authenticated responses use `private, no-store`; the legal-form catalog may use `private, max-age=86400`. schema: type: string X-Paywise-Environment: description: Environment that produced the response. schema: enum: - production - sandbox type: string X-Paywise-Request-Id: description: >- Fresh server-assigned correlation id for this response. Caller-provided request ids are ignored. schema: format: uuid type: string '403': content: application/json: schema: $ref: '#/components/schemas/Error' description: Standard error response. headers: Cache-Control: description: >- Cacheability directive. Authenticated responses use `private, no-store`; the legal-form catalog may use `private, max-age=86400`. schema: type: string X-Paywise-Environment: description: Environment that produced the response. schema: enum: - production - sandbox type: string X-Paywise-Request-Id: description: >- Fresh server-assigned correlation id for this response. Caller-provided request ids are ignored. schema: format: uuid type: string '409': content: application/json: schema: $ref: '#/components/schemas/Error' description: Standard error response. headers: Cache-Control: description: >- Cacheability directive. Authenticated responses use `private, no-store`; the legal-form catalog may use `private, max-age=86400`. schema: type: string X-Paywise-Environment: description: Environment that produced the response. schema: enum: - production - sandbox type: string X-Paywise-Request-Id: description: >- Fresh server-assigned correlation id for this response. Caller-provided request ids are ignored. schema: format: uuid type: string '429': content: application/json: schema: $ref: '#/components/schemas/Error' description: Standard error response. headers: Cache-Control: description: >- Cacheability directive. Authenticated responses use `private, no-store`; the legal-form catalog may use `private, max-age=86400`. schema: type: string Retry-After: description: Integer seconds to wait before retrying a throttled request. schema: minimum: 1 type: integer X-Paywise-Environment: description: Environment that produced the response. schema: enum: - production - sandbox type: string X-Paywise-Request-Id: description: >- Fresh server-assigned correlation id for this response. Caller-provided request ids are ignored. schema: format: uuid type: string '500': content: application/json: schema: $ref: '#/components/schemas/Error' description: Standard error response. headers: Cache-Control: description: >- Cacheability directive. Authenticated responses use `private, no-store`; the legal-form catalog may use `private, max-age=86400`. schema: type: string X-Paywise-Environment: description: Environment that produced the response. schema: enum: - production - sandbox type: string X-Paywise-Request-Id: description: >- Fresh server-assigned correlation id for this response. Caller-provided request ids are ignored. schema: format: uuid type: string security: - partnerBearerAuth: [] components: schemas: PartnerWebhookRequest: description: Resource representation with a native UUID `id`. properties: companies: description: >- Company selector for case and Mahnservice events: the string "*" includes every company with available partner case access, including companies added later; otherwise a JSON array of 1–500 accessible company UUIDs. Null makes the subscription lifecycle-only: no company case or Mahnservice events are delivered. Required for explicit case event types; omitted on PATCH preserves the selector. nullable: true description: description: Optional single-line label for this webhook. maxLength: 255 type: string enabled: description: >- Whether new deliveries can be sent to this endpoint. Defaults to true on creation. The endpoint is automatically disabled after its configured consecutive terminal-failure threshold is reached. Re-enable it after resolving the delivery problem. type: boolean events: description: >- Event types this endpoint receives. Omitted on creation, defaults to all Partner lifecycle events; omitted on PATCH, preserves the selection. Use ["*"] alone to subscribe to all event types, with case events delivered only when a companies selector is configured. Explicit case event types require companies. items: $ref: '#/components/schemas/PartnerWebhookSubscriptionEventEnum' type: array max_consecutive_failures: description: >- Automatically disables the endpoint when this many consecutive deliveries reach terminal failure. Retry attempts within one delivery do not each count. Raising it above the failure count of an automatically disabled endpoint makes that endpoint count toward the endpoint limit again and requires a free slot. maximum: 1000 minimum: 1 type: integer url: description: >- Publicly reachable HTTPS URL that receives webhook POST deliveries. The URL must be unique among this partner's v2 webhook endpoints. A Partner can register at most 20 webhook endpoints. Enabled and manually disabled endpoints count toward this limit; automatically disabled endpoints do not. Creating one more returns 409 webhook_limit_reached; delete an unused endpoint to free capacity. format: uri maxLength: 2048 minLength: 1 type: string required: - url type: object PartnerWebhookWithSecret: description: Resource representation with a native UUID `id`. properties: auto_disabled: description: >- `true` when the endpoint was disabled automatically after reaching `max_consecutive_failures`; re-enable it with `enabled: true` once the destination is fixed. Auto-disabled endpoints do not count toward the endpoint limit. readOnly: true type: boolean companies: description: >- Company selector for case and Mahnservice events: the string "*" includes every company with available partner case access, including companies added later; otherwise a JSON array of 1–500 accessible company UUIDs. Null makes the subscription lifecycle-only: no company case or Mahnservice events are delivered. Required for explicit case event types; omitted on PATCH preserves the selector. nullable: true consecutive_failures: description: >- Consecutive terminal delivery failures counted against this endpoint. A successful delivery resets the counter to zero. readOnly: true type: integer created_at: description: Time at which the webhook subscription was created. format: date-time readOnly: true type: string description: description: Optional single-line label for this webhook. maxLength: 255 type: string enabled: description: >- Whether deliveries are attempted. Re-enabling an endpoint resets its consecutive failure counter. Auto-disabled endpoints do not count toward the endpoint limit, so re-enabling one requires a free slot; otherwise the request returns 409 webhook_limit_reached. type: boolean events: description: >- Event types this endpoint receives. Use ["*"] alone to subscribe to all event types, with case events delivered only when a companies selector is configured. Explicit case event types require companies. items: $ref: '#/components/schemas/PartnerWebhookSubscriptionEventEnum' type: array id: description: Stable identifier for this resource. format: uuid readOnly: true type: string last_failure_at: description: >- Time of the latest counted terminal delivery failure since the last success; null before any failure or after a successful delivery. format: date-time nullable: true readOnly: true type: string max_consecutive_failures: description: >- Automatically disables the endpoint when this many consecutive deliveries reach terminal failure. Retry attempts within one delivery do not each count. Raising it above the failure count of an automatically disabled endpoint makes that endpoint count toward the endpoint limit again and requires a free slot. maximum: 1000 minimum: 1 type: integer secret_key: description: >- Signing secret shown once on creation or rotation. Store it to verify webhook signatures; list, retrieve, and idempotent replay responses omit it. readOnly: true type: string updated_at: description: Time at which the webhook subscription was last updated. format: date-time readOnly: true type: string url: description: >- Publicly reachable HTTPS URL that receives webhook POST deliveries. The URL must be unique among this partner's v2 webhook endpoints. format: uri maxLength: 2048 type: string required: - auto_disabled - consecutive_failures - created_at - id - last_failure_at - updated_at - url type: object Error: properties: code: description: Machine-readable error category. type: string detail: description: Short human-readable summary of the error. type: string errors: description: Field-level validation errors, when applicable. items: $ref: '#/components/schemas/ErrorItem' type: array required: - detail - code type: object PartnerWebhookSubscriptionEventEnum: description: >- * `*` - * * `company.created` - company.created * `company.case_submission_readiness.changed` - company.case_submission_readiness.changed * `company.access.confirmed` - company.access.confirmed * `company.access.revoked` - company.access.revoked * `company.access.restored` - company.access.restored * `company.user.added` - company.user.added * `company.user.revoked` - company.user.revoked * `company.user.activated` - company.user.activated * `company.user.invite_expired` - company.user.invite_expired * `order.submitted` - order.submitted * `order.withdrawn` - order.withdrawn * `order.rejected` - order.rejected * `order.accepted` - order.accepted * `order.expired` - order.expired * `mandate.created` - mandate.created * `mandate.state.changed` - mandate.state.changed * `mandate.status_update.published` - mandate.status_update.published * `mandate.balance_updated` - mandate.balance_updated * `order.message.created` - order.message.created * `mandate.message.created` - mandate.message.created * `request_to_client.created` - request_to_client.created * `request_to_client.answered` - request_to_client.answered * `payment.reported` - payment.reported * `statement.published` - statement.published * `statement.cancelled` - statement.cancelled * `single_mandate_statement.published` - single_mandate_statement.published * `single_mandate_statement.cancelled` - single_mandate_statement.cancelled * `mandate.correspondence.published` - mandate.correspondence.published * `invoice.created` - invoice.created * `invoice.paid` - invoice.paid * `invoice.cancelled` - invoice.cancelled * `invoice.written_off` - invoice.written_off * `invoice.reopened` - invoice.reopened * `dunning.level_advanced` - dunning.level_advanced * `dunning.handed_to_collection` - dunning.handed_to_collection enum: - '*' - company.created - company.case_submission_readiness.changed - company.access.confirmed - company.access.revoked - company.access.restored - company.user.added - company.user.revoked - company.user.activated - company.user.invite_expired - order.submitted - order.withdrawn - order.rejected - order.accepted - order.expired - mandate.created - mandate.state.changed - mandate.status_update.published - mandate.balance_updated - order.message.created - mandate.message.created - request_to_client.created - request_to_client.answered - payment.reported - statement.published - statement.cancelled - single_mandate_statement.published - single_mandate_statement.cancelled - mandate.correspondence.published - invoice.created - invoice.paid - invoice.cancelled - invoice.written_off - invoice.reopened - dunning.level_advanced - dunning.handed_to_collection type: string ErrorItem: properties: code: description: Machine-readable field error code. type: string field: description: >- Path to the field that caused the error, using dots for objects and brackets for list indexes, for example `claims[0].amount`; null for an error without a field path. nullable: true type: string message: description: Human-readable explanation of the field error. type: string required: - field - code - message type: object securitySchemes: partnerBearerAuth: description: >- Partner API Bearer key: `Authorization: Bearer `. Keys are created only through authorized portal or staff flows. scheme: bearer type: http ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.