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

# Webhook

::: info
Os webhooks são referenciados por [gatilhos](/pt_BR/reference/rest-api/trigger) por meio
da ação perform `notification.webhook`
(`{"notification.webhook": {"webhook_id": <id>}}`). Crie o webhook
primeiro e depois aponte um ou mais gatilhos para o `id` dele.
:::

## Listar

Permissão necessária: `admin.webhook`

Solicitação `GET` enviada: `/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` e `bearer_token` são retornados
como `**********` depois de definidos. A API nunca retorna os segredos
armazenados. Campos não definidos são retornados como `null`.
:::

## Mostrar

Permissão necessária: `admin.webhook`

Solicitação `GET` enviada: `/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"
}

```

:::

## Criar

Permissão necessária: `admin.webhook`

Solicitação `POST` enviada: `/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` importa para endpoints `https://`: defina-o como `true` para realmente
validar o certificado TLS do endpoint. Só faz sentido defini-lo como
`false` para um endpoint `http://` simples, que de qualquer forma não tem certificado a
verificar.
:::

## Atualização

Permissão necessária: `admin.webhook`

Solicitação `PUT` enviada: `/api/v1/webhooks/{id}`

O formato do payload é idêntico ao de Create. A resposta é o registro
atualizado, no mesmo formato de Show/Create, com `updated_at` atualizado.

::: tip
Um payload parcial também funciona, por exemplo `{"active": false}` para alternar apenas
esse campo.
:::

:::: 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"
}

```

:::

::::

## Excluir

Permissão necessária: `admin.webhook`

::: danger
**Esta é uma remoção permanente**

Observe que remover webhooks não pode ser desfeito.
:::

Um webhook que ainda é referenciado pela ação `perform` de outro objeto (por
exemplo, um [gatilho](/pt_BR/reference/rest-api/trigger)) não pode ser
excluído. A API responde com `422 Unprocessable Entity` e lista os objetos
que fazem a referência. Remova a referência primeiro.

Solicitação `DELETE` enviada: `/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)"
  ]
}

```

:::
