---
url: https://next.zammad.org/it/reference/rest-api/webhook.md
---

# Webhook

::: info
Webhooks are referenced by [triggers](/en/reference/rest-api/trigger) via
the `notification.webhook` perform action
(`{"notification.webhook": {"webhook_id": <id>}}`). Create the webhook
first, then point one or more triggers at its `id`.
:::

## Elenca

Required permission: `admin.webhook`

`GET`-Request sent: `/api/v1/webhooks`

::: details

```json
// HTTP-Code 200 OK

[
  {
    "id": 1,
    "name": "Example webhook",
    "endpoint": "https://example.com/webhooks/incoming",
    "http_method": "post",
    "signature_token": "**********",
    "ssl_verify": true,
    "basic_auth_username": "user",
    "basic_auth_password": "**********",
    "bearer_token": null,
    "note": "Notifies an external system about ticket updates.",
    "pre_defined_webhook_type": null,
    "customized_payload": false,
    "custom_payload": null,
    "preferences": {},
    "active": true,
    "updated_by_id": 3,
    "created_by_id": 3,
    "created_at": "2026-09-24T12:31:34.578Z",
    "updated_at": "2026-09-24T12:31:44.512Z"
  }
]

```

:::

::: info
`signature_token`, `basic_auth_password` and `bearer_token` are returned
as `**********` once they're set. The API never returns the stored
secrets. Fields that aren't set are returned as `null`.
:::

## Mostra

Required permission: `admin.webhook`

`GET`-Request sent: `/api/v1/webhooks/{id}`

::: details

```json
// HTTP-Code 200 OK

{
  "id": 1,
  "name": "Example webhook",
  "endpoint": "https://example.com/webhooks/incoming",
  "http_method": "post",
  "signature_token": "**********",
  "ssl_verify": true,
  "basic_auth_username": "user",
  "basic_auth_password": "**********",
  "bearer_token": null,
  "note": "Notifies an external system about ticket updates.",
  "pre_defined_webhook_type": null,
  "customized_payload": false,
  "custom_payload": null,
  "preferences": {},
  "active": true,
  "updated_by_id": 3,
  "created_by_id": 3,
  "created_at": "2026-09-24T12:31:34.578Z",
  "updated_at": "2026-09-24T12:31:44.512Z"
}

```

:::

## Crea

Required permission: `admin.webhook`

`POST`-Request sent: `/api/v1/webhooks`

:::: details

::: tabs key:reqres

\=== Request

```json
{
  "name": "Example webhook",
  "endpoint": "https://example.com/webhooks/incoming",
  "http_method": "post",
  "signature_token": "your-signature-token",
  "ssl_verify": true,
  "customized_payload": false,
  "note": "Notifies an external system about ticket updates.",
  "active": true
}

```

\=== Response

```json
// HTTP-Code 201 Created

{
  "id": 1,
  "name": "Example webhook",
  "endpoint": "https://example.com/webhooks/incoming",
  "http_method": "post",
  "signature_token": "**********",
  "ssl_verify": true,
  "basic_auth_username": null,
  "basic_auth_password": null,
  "bearer_token": null,
  "note": "Notifies an external system about ticket updates.",
  "pre_defined_webhook_type": null,
  "customized_payload": false,
  "custom_payload": null,
  "preferences": {},
  "active": true,
  "updated_by_id": 3,
  "created_by_id": 3,
  "created_at": "2026-09-24T12:31:34.578Z",
  "updated_at": "2026-09-24T12:31:34.578Z"
}

```

:::

::::

::: info
`ssl_verify` matters for `https://` endpoints, set it `true` to actually
validate the endpoint's TLS certificate. It only makes sense to set it
`false` for a plain `http://` endpoint, which has no certificate to
verify in the first place.
:::

## Aggiornamento

Required permission: `admin.webhook`

`PUT`-Request sent: `/api/v1/webhooks/{id}`

Payload shape is identical to Create. The response is the updated record,
same shape as Show/Create with `updated_at` refreshed.

::: tip
A partial payload works too, e.g. `{"active": false}` to toggle just
that field.
:::

:::: details

::: tabs key:reqres

\=== Request

```json
{
  "name": "Example webhook",
  "endpoint": "https://example.com/webhooks/incoming",
  "http_method": "post",
  "signature_token": "your-signature-token",
  "ssl_verify": true,
  "customized_payload": false,
  "note": "Notifies an external system about ticket updates.",
  "active": true,
  "id": 1
}

```

\=== Response

```json
// HTTP-Code 200 OK

{
  "id": 1,
  "name": "Example webhook",
  "endpoint": "https://example.com/webhooks/incoming",
  "http_method": "post",
  "signature_token": "**********",
  "ssl_verify": true,
  "basic_auth_username": null,
  "basic_auth_password": null,
  "bearer_token": null,
  "note": "Notifies an external system about ticket updates.",
  "pre_defined_webhook_type": null,
  "customized_payload": false,
  "custom_payload": null,
  "preferences": {},
  "active": true,
  "updated_by_id": 3,
  "created_by_id": 3,
  "created_at": "2026-09-24T12:31:34.578Z",
  "updated_at": "2026-09-24T12:31:48.115Z"
}

```

:::

::::

## Elimina

Required permission: `admin.webhook`

::: danger
**This is a permanent removal**

Please note that removing webhooks cannot be undone.
:::

A webhook that is still referenced by the `perform` action of another object
(e.g. a [trigger](/en/reference/rest-api/trigger)) can't be deleted. The API
responds with `422 Unprocessable Entity` and lists the referencing
objects. Remove the reference first.

`DELETE`-Request sent: `/api/v1/webhooks/{id}`

::: details

```json
// HTTP-Code 200 OK

{}

```

:::

::: details

```json
// HTTP-Code 422 Unprocessable Entity

{
  "error": "This object is referenced by other object(s) and thus cannot be deleted: %s",
  "error_human": "This object is referenced by other object(s) and thus cannot be deleted: %s",
  "unprocessable_content": [
    "Trigger / Notify customer on auto-close (#5)"
  ]
}

```

:::
