Menu

Webhooks

Subscribe to events with HMAC-signed delivery, exponential retries, and dead-letter replay.

Endpoints


GET /api/v1/companies/:companyId/webhooks

webhooks.list · scope webhooks:manage

List webhook subscriptions for a company.

Returns all webhook subscriptions for the company. The HMAC signing secret is never exposed by this endpoint: it is returned exactly once when the webhook is created.

Use when: You need to enumerate the webhook subscriptions an integration has registered, e.g. to build a UI listing or sync state with an external system.

Don't use for: Reading delivery history (use GET /webhooks/{id}/deliveries). Reading the secret (it is unrecoverable after the create response: generate a new webhook if lost).

Pitfalls

  • Disabled webhooks (auto-disabled after HTTP 410, or manually disabled via PATCH) appear in the list with active=false and a disabled_reason.
  • verification_status tells whether events reach the URL: 'verified' and 'grace_period' receive events; 'pending' (new or changed URL) and 'paused' (a pre-verification endpoint whose grace window closed) receive nothing until the URL passes the handshake (POST /webhooks/{id}/verify).

Risk: low · Idempotent: yes · Reversible: no · Dry-run supported: no

Response fields

NameTypeDescription
webhooks[].idstring
webhooks[].handlestring (optional)Typed handle of this webhook: wh_ plus its id as 32 lowercase hex. Accepted wherever the id is.
webhooks[].namestring
webhooks[].event_typestringThe first of event_types, kept for clients that read a single type.
webhooks[].event_typesstring[]Every event type this webhook receives.
webhooks[].webhook_urlstring
webhooks[].activeboolean
webhooks[].api_version_pinnedstring
webhooks[].disabled_atstring | null
webhooks[].disabled_reasonstring | null
webhooks[].created_atstring
webhooks[].verification_status"verified" | "pending" | "grace_period" | "paused"
webhooks[].verified_atstring | null
webhooks[].verification_grace_ends_atstring | null
webhooks[].verification_attemptsnumber
webhooks[].verification_last_attempt_atstring | null
webhooks[].verification_last_errorstring | null
webhooks[].verification_next_attempt_atstring | null

Example response

{
  "data": {
    "webhooks": [
      {
        "id": "a8f1…",
        "name": "CRM sync",
        "event_type": "invoice.paid",
        "event_types": [
          "invoice.paid",
          "credit_note.created"
        ],
        "webhook_url": "https://example.com/hooks/gnubok",
        "active": true,
        "api_version_pinned": "2026-05-12",
        "disabled_at": null,
        "disabled_reason": null,
        "created_at": "2026-05-15T12:00:00Z",
        "verification_status": "verified",
        "verified_at": "2026-05-15T12:01:02Z",
        "verification_grace_ends_at": null,
        "verification_attempts": 1,
        "verification_last_attempt_at": "2026-05-15T12:01:02Z",
        "verification_last_error": null,
        "verification_next_attempt_at": null
      }
    ]
  },
  "meta": {
    "request_id": "req_…",
    "api_version": "2026-05-12"
  }
}

GET /api/v1/companies/:companyId/webhooks/:id

webhooks.get · scope webhooks:manage

Get a webhook subscription by id.

Returns the webhook configuration and its endpoint verification state. The HMAC signing secret is never exposed.

Use when: You need the current state of a single webhook (e.g. to render a settings page, or to see why verification_status is not verified: verification_last_error).

Don't use for: Reading the secret (returned only once on creation).

Pitfalls

  • Only 'verified' and 'grace_period' endpoints receive events. 'grace_period' ends at verification_grace_ends_at, after which the endpoint is 'paused' until it passes the handshake.

Risk: low · Idempotent: yes · Reversible: no · Dry-run supported: no

Response fields

NameTypeDescription
idstring
handlestring (optional)Typed handle of this webhook: wh_ plus its id as 32 lowercase hex. Accepted wherever the id is.
namestring
descriptionstring | null
event_typestringThe first of event_types, kept for clients that read a single type.
event_typesstring[]Every event type this webhook receives.
webhook_urlstring
activeboolean
api_version_pinnedstring
disabled_atstring | null
disabled_reasonstring | null
created_atstring
updated_atstring
verification_status"verified" | "pending" | "grace_period" | "paused"
verified_atstring | null
verification_grace_ends_atstring | null
verification_attemptsnumber
verification_last_attempt_atstring | null
verification_last_errorstring | null
verification_next_attempt_atstring | null

Example response

{
  "data": {
    "id": "a8f1…",
    "name": "CRM sync",
    "description": null,
    "event_type": "invoice.paid",
    "event_types": [
      "invoice.paid"
    ],
    "webhook_url": "https://example.com/hooks/gnubok",
    "active": true,
    "api_version_pinned": "2026-05-12",
    "disabled_at": null,
    "disabled_reason": null,
    "created_at": "2026-05-15T12:00:00Z",
    "updated_at": "2026-05-15T12:00:00Z",
    "verification_status": "verified",
    "verified_at": "2026-05-15T12:01:02Z",
    "verification_grace_ends_at": null,
    "verification_attempts": 1,
    "verification_last_attempt_at": "2026-05-15T12:01:02Z",
    "verification_last_error": null,
    "verification_next_attempt_at": null
  },
  "meta": {
    "request_id": "req_…",
    "api_version": "2026-05-12"
  }
}

GET /api/v1/companies/:companyId/webhooks/:id/deliveries

webhooks.deliveries.list · scope webhooks:manage

List deliveries for a webhook subscription.

Returns deliveries for the webhook in newest-first order. Each row carries the current status (pending / in_flight / delivered / failed / dead), the attempt count, the next scheduled retry time, and the captured response details from the last attempt.

Use when: You are debugging a flaky receiver, or building a delivery-history UI for a settings page.

Don't use for: Listing deliveries across multiple webhooks (this endpoint is single-webhook scoped).

Pitfalls

  • response_body is truncated to 4 KB: receivers returning long error pages have their response truncated.
  • A delivery in failed status is non-terminal: the dispatcher will retry it at next_attempt_at. dead is terminal.

Risk: low · Idempotent: yes · Reversible: no · Dry-run supported: no

Query parameters

NameTypeRequiredDescription
cursorstringnoOpaque cursor from the previous page's meta.next_cursor. Omit for the first page.
limitnumbernoPage size, 1-100 (default 50). Larger values are clamped to 100.
delivery_idstringnoReturn only this delivery (its id). Combine with the webhook id in the path.

Response fields

NameTypeDescription
[].idstring
[].handlestring (optional)Typed handle of this webhook delivery: whd_ plus its id as 32 lowercase hex. Accepted wherever the id is.
[].webhook_idstring
[].event_typestring
[].status"pending" | "in_flight" | "delivered" | "failed" | "dead"
[].attemptsnumber
[].next_attempt_atstring
[].response_statusnumber | null
[].response_bodystring | null
[].errorstring | null
[].request_idstring | null
[].created_atstring
[].delivered_atstring | null

Example response

{
  "data": [
    {
      "id": "wh_dlv_…",
      "webhook_id": "a8f1…",
      "event_type": "invoice.paid",
      "status": "delivered",
      "attempts": 1,
      "next_attempt_at": "2026-05-15T12:00:00Z",
      "response_status": 200,
      "response_body": "ok",
      "error": null,
      "request_id": "whdel_…",
      "created_at": "2026-05-15T12:00:00Z",
      "delivered_at": "2026-05-15T12:00:01Z"
    }
  ],
  "meta": {
    "request_id": "req_…",
    "api_version": "2026-05-12",
    "next_cursor": null
  }
}

POST /api/v1/companies/:companyId/webhooks

webhooks.create · scope webhooks:manage

Register a webhook subscription.

Creates a webhook subscription for one or more event types (event_types; the single event_type is still accepted). Each delivery carries one event, named by its type field and the X-Gnubok-Event header. The response includes a freshly generated HMAC signing secret, returned EXACTLY ONCE: store it on the receiver side immediately. The webhook is pinned to the current API version on creation; payload shapes for this webhook will not change until you explicitly upgrade. The webhook starts with verification_status 'pending': no event is delivered until the URL passes the ownership handshake. Accounted POSTs a signed webhook.verification event whose data.object.challenge your endpoint must return as {"challenge": "<value>"} with a 2xx within 10 seconds; call POST /webhooks/{id}/verify once your receiver answers it, or let the automatic attempts (after 1m, 5m, 30m, 2h, 12h, then daily, 8 in all) pick it up.

Use when: You are wiring a downstream integration that needs push notifications instead of polling.

Don't use for: Subscribing to internal MCP telemetry events (mcp.tool_called etc. are not delivered as webhooks). Replacing an existing webhook URL: use PATCH instead.

Pitfalls

  • The secret is returned exactly once. If lost, rotate it with POST /webhooks/{id}/rotate-secret: a fresh secret is issued in place, the webhook id and delivery history are kept.
  • Listing salary_run.* or agi.generated in event_types requires payroll:read in addition to webhooks:manage, as for a single event_type.
  • A receiver that missed deliveries catches up from GET /api/events (scope events:read), which serves every deliverable event type from a sequence cursor.
  • Delivery is at-least-once with exponential backoff (1m / 5m / 30m / 2h / 12h / 24h / 48h). Receivers MUST be idempotent.
  • HTTP 410 from your receiver auto-disables the webhook (sets active=false + disabled_reason).
  • Events emitted while verification_status is 'pending' are not delivered later: they are skipped, as for a disabled webhook. Verify before you depend on the webhook.

Risk: low · Idempotent: yes · Reversible: yes · Dry-run supported: yes

Query parameters

NameTypeRequiredDescription
dry_runstringnotrue (any case) previews the write without committing it, like the X-Dry-Run: true header. Any other value commits.

Request body

NameTypeRequiredDescription
event_types("invoice.created" | "invoice.sent" | "invoice.paid" | "credit_note.created" | "supplier.created" | "supplier_invoice.registered" | "supplier_invoice.approved" | "supplier_invoice.paid" | "supplier_invoice.credited" | "supplier_invoice.uncredited" | "customer.created" | "dimension_value.created" | "dimension_value.renamed" | "dimension_value.archived" | "dimension_value.unarchived" | "journal_entry.committed" | "journal_entry.reversed" | "journal_entry.corrected" | "transaction.categorized" | "transaction.reconciled" | "reconciliation.matched" | "reconciliation.unmatched" | "reconciliation.signed_off" | "reconciliation.reopened" | "period.locked" | "period.unlocked" | "period.year_closed" | "period.lock_date_changed" | "salary_run.created" | "salary_run.approved" | "salary_run.booked" | "agi.generated" | "document.uploaded" | "signing.signer_signed" | "signing.declined" | "signing.completed")[]noEvent types this webhook receives, one or more. Required unless event_type is sent.
event_type"invoice.created" | "invoice.sent" | "invoice.paid" | "credit_note.created" | "supplier.created" | "supplier_invoice.registered" | "supplier_invoice.approved" | "supplier_invoice.paid" | "supplier_invoice.credited" | "supplier_invoice.uncredited" | "customer.created" | "dimension_value.created" | "dimension_value.renamed" | "dimension_value.archived" | "dimension_value.unarchived" | "journal_entry.committed" | "journal_entry.reversed" | "journal_entry.corrected" | "transaction.categorized" | "transaction.reconciled" | "reconciliation.matched" | "reconciliation.unmatched" | "reconciliation.signed_off" | "reconciliation.reopened" | "period.locked" | "period.unlocked" | "period.year_closed" | "period.lock_date_changed" | "salary_run.created" | "salary_run.approved" | "salary_run.booked" | "agi.generated" | "document.uploaded" | "signing.signer_signed" | "signing.declined" | "signing.completed"noA single event type, accepted for clients written before event_types. When both are sent it must be one of event_types.
webhook_urlstringyes
namestringyes
descriptionstringno

Response fields

NameTypeDescription
idstring
handlestring (optional)Typed handle of this webhook: wh_ plus its id as 32 lowercase hex. Accepted wherever the id is.
namestring
event_typestringThe first of event_types, kept for clients that read a single type.
event_typesstring[]Every event type this webhook receives.
webhook_urlstring
activeboolean
api_version_pinnedstring
disabled_atstring | null
disabled_reasonstring | null
created_atstring
verification_status"verified" | "pending" | "grace_period" | "paused"
verified_atstring | null
verification_grace_ends_atstring | null
verification_attemptsnumber
verification_last_attempt_atstring | null
verification_last_errorstring | null
verification_next_attempt_atstring | null
secretstring
descriptionstring | null

Example request

{
  "event_types": [
    "invoice.paid",
    "credit_note.created"
  ],
  "webhook_url": "https://example.com/hooks/gnubok",
  "name": "CRM sync"
}

Example response

{
  "data": {
    "id": "a8f1…",
    "name": "CRM sync",
    "event_type": "invoice.paid",
    "event_types": [
      "invoice.paid",
      "credit_note.created"
    ],
    "webhook_url": "https://example.com/hooks/gnubok",
    "active": true,
    "api_version_pinned": "2026-05-12",
    "disabled_at": null,
    "disabled_reason": null,
    "secret": "whsec_…",
    "description": null,
    "created_at": "2026-05-15T12:00:00Z",
    "verification_status": "pending",
    "verified_at": null,
    "verification_grace_ends_at": null,
    "verification_attempts": 0,
    "verification_last_attempt_at": null,
    "verification_last_error": null,
    "verification_next_attempt_at": "2026-05-15T12:00:00Z"
  },
  "meta": {
    "request_id": "req_…",
    "api_version": "2026-05-12"
  }
}

POST /api/v1/companies/:companyId/webhooks/:id/rotate-secret

webhooks.rotate_secret · scope webhooks:manage

Rotate the HMAC signing secret on a webhook.

Generates a fresh HMAC signing secret for the webhook and returns it EXACTLY ONCE. The previous secret is invalidated immediately. There is no grace period: coordinate the rotation on the receiver side BEFORE calling this endpoint, or temporarily disable the webhook (PATCH active=false) to pause delivery while you swap secrets.

Use when: After a suspected secret leak, on a routine rotation cadence (Stripe pattern: every 90 days for compliance-grade integrations), or when changing the receiver implementation and you want to invalidate the old secret deliberately.

Don't use for: Routine integration setup: the secret returned at create time is the canonical one. Recovering a lost secret (rotation does not recover the prior value; it issues a fresh one).

Pitfalls

  • The secret is returned exactly once. If you lose this response, the recovery path is to rotate again.
  • In-flight deliveries between the rotation and the receiver-side update may fail signature verification on the new secret. Pause the webhook (PATCH active=false) first if your tolerance for that window is zero.

Risk: medium · Idempotent: yes · Reversible: no · Dry-run supported: no

Response fields

NameTypeDescription
idstring
handlestring (optional)Typed handle of this webhook: wh_ plus its id as 32 lowercase hex. Accepted wherever the id is.
secretstring
rotated_atstring

Example response

{
  "data": {
    "id": "a8f1…",
    "secret": "whsec_…",
    "rotated_at": "2026-05-15T12:00:00Z"
  },
  "meta": {
    "request_id": "req_…",
    "api_version": "2026-05-12"
  }
}

POST /api/v1/companies/:companyId/webhooks/:id/test

webhooks.test · scope webhooks:manage

Send a synthetic test event to a webhook.

Enqueues a webhook.test delivery against the configured receiver and dispatches it immediately, so the outcome is normally available within a second or two rather than on the next per-minute cron tick. Use the returned webhook_delivery_id to poll GET /webhooks/{id}/deliveries for the outcome.

Use when: After creating or modifying a webhook, before relying on it in production: to validate that the receiver is reachable and that signature verification works on the receiver side.

Don't use for: Smoke-testing the dispatcher itself (use a real event). Replaying a failed delivery (use POST /webhook-deliveries/{id}/retry).

Pitfalls

  • Test deliveries follow the same retry policy as real events: a 500 from your receiver will retry 7 times over ~87h (about 3.6 days). Use a 2xx ack-only handler if you want a clean signal.
  • A test event is an event: an endpoint whose verification_status is 'pending' or 'paused' answers 409 WEBHOOK_NOT_VERIFIED. Verify it first with POST /webhooks/{id}/verify.

Risk: low · Idempotent: no · Reversible: no · Dry-run supported: no

Response fields

NameType
webhook_delivery_idstring
status"pending"

Example response

{
  "data": {
    "webhook_delivery_id": "wh_dlv_…",
    "status": "pending"
  },
  "meta": {
    "request_id": "req_…",
    "api_version": "2026-05-12"
  }
}

POST /api/v1/companies/:companyId/webhooks/:id/verify

webhooks.verify · scope webhooks:manage

Verify a webhook endpoint's ownership now.

Runs the ownership handshake against the webhook URL immediately and returns the result. Accounted POSTs a signed webhook.verification event (same X-Gnubok-Signature scheme and envelope as every delivery) whose data.object.challenge is a random value; the endpoint passes by answering, within 10 seconds and without a redirect, any 2xx with the JSON body {"challenge": "<the same value>"}. A pass sets verified_at and opens the webhook to deliveries; a failure answers 422 WEBHOOK_VERIFICATION_FAILED with details.reason. A webhook that is already verified is returned as-is without contacting the URL.

Use when: After creating a webhook or changing its URL, once your receiver answers webhook.verification. Also to resume a webhook whose verification_status is 'paused' (a pre-verification endpoint whose grace window closed).

Don't use for: Checking that normal deliveries work end to end (use POST /webhooks/{id}/test once verified). Re-verifying a verified URL: the call is a no-op until the URL changes.

Pitfalls

  • The challenge is inside data.object but must come back at the top level of your response body: {"challenge": "..."}. Echoing the request body verbatim does not pass.
  • One attempt per webhook per 10 seconds: a faster repeat answers 429 RATE_LIMITED with Retry-After.
  • A disabled webhook (active=false or auto-disabled) answers 400: re-enable it with PATCH first.
  • Reasons in details.reason / verification_last_error: http_<status>, timeout, redirect_blocked, response_not_json, response_too_large, challenge_missing, challenge_mismatch, transport_error, url_unsafe:<class>.

Risk: low · Idempotent: yes · Reversible: no · Dry-run supported: no

Response fields

NameTypeDescription
idstring
handlestring (optional)Typed handle of this webhook: wh_ plus its id as 32 lowercase hex. Accepted wherever the id is.
webhook_urlstring
verification_status"verified" | "pending" | "grace_period" | "paused"
verified_atstring | null
verification_grace_ends_atstring | null
verification_attemptsnumber
verification_last_attempt_atstring | null
verification_last_errorstring | null
verification_next_attempt_atstring | null

Example response

{
  "data": {
    "id": "a8f1…",
    "webhook_url": "https://example.com/hooks/gnubok",
    "verification_status": "verified",
    "verified_at": "2026-05-15T12:01:02Z",
    "verification_grace_ends_at": null,
    "verification_attempts": 1,
    "verification_last_attempt_at": "2026-05-15T12:01:02Z",
    "verification_last_error": null,
    "verification_next_attempt_at": null
  },
  "meta": {
    "request_id": "req_…",
    "api_version": "2026-05-12"
  }
}

POST /api/v1/webhook-deliveries/:id/retry

webhook_deliveries.retry · scope webhooks:manage

Retry a webhook delivery.

Re-enqueues a dead (or delivered) delivery as a fresh pending row. The new delivery references the same webhook + payload; the dispatcher is kicked at once, and the per-minute cron picks it up if that attempt is missed. The original row is preserved in the audit log.

Use when: After a receiver outage you want to replay deliveries that died, or after fixing a receiver-side bug you want to redeliver a successful one.

Don't use for: Retrying live deliveries (pending / in_flight / failed): the dispatcher is already managing them.

Pitfalls

  • Retrying a delivered delivery causes the receiver to see the event twice. Receivers MUST be idempotent (check the X-Gnubok-Delivery header).
  • Every call queues a new delivery with its own X-Gnubok-Delivery id. Send an Idempotency-Key: a repeat with the same key answers the first call's webhook_delivery_id (Idempotent-Replayed: true) instead of queueing another.
  • The webhook must be deliverable: an endpoint whose verification_status is 'pending' or 'paused' answers 409 WEBHOOK_NOT_VERIFIED until it passes POST /webhooks/{id}/verify.

Risk: medium · Idempotent: no · Reversible: no · Dry-run supported: no

Response fields

NameType
webhook_delivery_idstring
status"pending"

Example response

{
  "data": {
    "webhook_delivery_id": "wh_dlv_NEW",
    "status": "pending"
  },
  "meta": {
    "request_id": "req_…",
    "api_version": "2026-05-12"
  }
}

PATCH /api/v1/companies/:companyId/webhooks/:id

webhooks.update · scope webhooks:manage

Update a webhook subscription.

Update the URL, name, description, active flag, or the event types the webhook receives (event_types replaces the list; a single event_type is still accepted). api_version_pinned is kept. Setting active=false manually pauses delivery without deleting; setting active=true clears any disabled_at/disabled_reason set by the auto-disable on HTTP 410. A new webhook_url resets verification to 'pending' (and ends any grace window): nothing is delivered to the new URL until it passes the ownership handshake, which Accounted attempts within a minute; POST /webhooks/{id}/verify runs it immediately.

Use when: You need to point an existing webhook at a new URL or temporarily pause delivery.

Don't use for: Rotating the signing secret: use POST /webhooks/{id}/rotate-secret, which issues a fresh secret in place and keeps the webhook id and delivery history.

Pitfalls

  • Re-enabling a webhook (active: true) does NOT replay deliveries that went to dead status while it was disabled: those need POST /webhook-deliveries/{id}/retry.
  • Changing webhook_url withholds deliveries until the new URL is verified: have the new receiver answer webhook.verification before you switch.
  • active: true does not bypass verification: a pending or paused endpoint stays without deliveries until it passes the handshake.
  • event_types replaces the whole list: send every type the webhook should keep. Listing salary_run.* or agi.generated requires payroll:read.

Risk: low · Idempotent: yes · Reversible: yes · Dry-run supported: yes

Query parameters

NameTypeRequiredDescription
dry_runstringnotrue (any case) previews the write without committing it, like the X-Dry-Run: true header. Any other value commits.

Request body

NameTypeRequiredDescription
namestringno
descriptionstring | nullno
webhook_urlstringno
activebooleanno
event_types("invoice.created" | "invoice.sent" | "invoice.paid" | "credit_note.created" | "supplier.created" | "supplier_invoice.registered" | "supplier_invoice.approved" | "supplier_invoice.paid" | "supplier_invoice.credited" | "supplier_invoice.uncredited" | "customer.created" | "dimension_value.created" | "dimension_value.renamed" | "dimension_value.archived" | "dimension_value.unarchived" | "journal_entry.committed" | "journal_entry.reversed" | "journal_entry.corrected" | "transaction.categorized" | "transaction.reconciled" | "reconciliation.matched" | "reconciliation.unmatched" | "reconciliation.signed_off" | "reconciliation.reopened" | "period.locked" | "period.unlocked" | "period.year_closed" | "period.lock_date_changed" | "salary_run.created" | "salary_run.approved" | "salary_run.booked" | "agi.generated" | "document.uploaded" | "signing.signer_signed" | "signing.declined" | "signing.completed")[]noReplaces the event types this webhook receives, one or more.
event_type"invoice.created" | "invoice.sent" | "invoice.paid" | "credit_note.created" | "supplier.created" | "supplier_invoice.registered" | "supplier_invoice.approved" | "supplier_invoice.paid" | "supplier_invoice.credited" | "supplier_invoice.uncredited" | "customer.created" | "dimension_value.created" | "dimension_value.renamed" | "dimension_value.archived" | "dimension_value.unarchived" | "journal_entry.committed" | "journal_entry.reversed" | "journal_entry.corrected" | "transaction.categorized" | "transaction.reconciled" | "reconciliation.matched" | "reconciliation.unmatched" | "reconciliation.signed_off" | "reconciliation.reopened" | "period.locked" | "period.unlocked" | "period.year_closed" | "period.lock_date_changed" | "salary_run.created" | "salary_run.approved" | "salary_run.booked" | "agi.generated" | "document.uploaded" | "signing.signer_signed" | "signing.declined" | "signing.completed"noA single event type, accepted for clients written before event_types: the webhook then receives only it. When both are sent it must be one of event_types.

Response fields

NameTypeDescription
idstring
handlestring (optional)Typed handle of this webhook: wh_ plus its id as 32 lowercase hex. Accepted wherever the id is.
namestring
descriptionstring | null
event_typestringThe first of event_types, kept for clients that read a single type.
event_typesstring[]Every event type this webhook receives.
webhook_urlstring
activeboolean
api_version_pinnedstring
disabled_atstring | null
disabled_reasonstring | null
created_atstring
updated_atstring
verification_status"verified" | "pending" | "grace_period" | "paused"
verified_atstring | null
verification_grace_ends_atstring | null
verification_attemptsnumber
verification_last_attempt_atstring | null
verification_last_errorstring | null
verification_next_attempt_atstring | null

Example request

{
  "active": true
}

Example response

{
  "data": {
    "id": "a8f1…",
    "name": "CRM sync",
    "description": null,
    "event_type": "invoice.paid",
    "event_types": [
      "invoice.paid"
    ],
    "webhook_url": "https://example.com/hooks/gnubok",
    "active": true,
    "api_version_pinned": "2026-05-12",
    "disabled_at": null,
    "disabled_reason": null,
    "created_at": "2026-05-15T12:00:00Z",
    "updated_at": "2026-05-15T12:05:00Z",
    "verification_status": "verified",
    "verified_at": "2026-05-15T12:01:02Z",
    "verification_grace_ends_at": null,
    "verification_attempts": 1,
    "verification_last_attempt_at": "2026-05-15T12:01:02Z",
    "verification_last_error": null,
    "verification_next_attempt_at": null
  },
  "meta": {
    "request_id": "req_…",
    "api_version": "2026-05-12"
  }
}

DELETE /api/v1/companies/:companyId/webhooks/:id

webhooks.delete · scope webhooks:manage

Delete a webhook subscription.

Hard-deletes the webhook. The delivery audit trail SURVIVES: both terminal (delivered, dead) and non-terminal (pending, failed) delivery rows persist with webhook_id = NULL so the BFNAR 2013:2 kap 8 § behandlingshistorik (7-year retention) for accounting-event deliveries is preserved. Non-terminal rows go dormant (the dispatcher skips them).

Use when: You no longer want this webhook to receive events.

Don't use for: Temporarily pausing delivery: use PATCH with active=false instead so the configuration survives.

Pitfalls

  • Audit history survives DELETE; only the receiver subscription is removed. To suppress future events without retaining the registration use PATCH active=false.

Risk: medium · Idempotent: yes · Reversible: no · Dry-run supported: no

Example response

{
  "data": {
    "deleted": true
  },
  "meta": {
    "request_id": "req_…",
    "api_version": "2026-05-12"
  }
}