---
title: "Webhooks (webhooks) no SDK Python da NFE.io"
description: "Cadastre, consulte, altere, teste e remova os webhooks da conta com client.webhooks e liste os tipos de evento disponíveis."
source_url: https://nfe.io/docs/desenvolvedores/bibliotecas/python/recursos/webhooks/
product: bibliotecas
last_updated: 2026-10-14
tags: ["python", "referencia", "webhook"]
integration: ["sdk"]
---

# Webhooks (`webhooks`)

`client.webhooks` administra os webhooks da conta (API v2 em `https://api.nfse.io`, com a
`api_key`). Para **receber** e verificar as entregas, veja o guia [Webhooks](../webhooks.md).

## Métodos

```python
webhooks.list(*, options=None) -> list[Webhook]
webhooks.retrieve(webhook_id, *, options=None) -> Webhook
webhooks.create(params, *, options=None) -> Webhook
webhooks.update(webhook_id, params, *, options=None) -> Webhook
webhooks.delete(webhook_id, *, options=None) -> None
webhooks.ping(webhook_id, *, options=None) -> None
webhooks.event_types(*, options=None) -> list[WebhookEventType]
```

## Criar

```python
from nfeio import NfeClient
from nfeio.types import WebhookParams

client = NfeClient()

params: WebhookParams = {
    "uri": "https://erp.exemplo.com.br/nfeio/webhook",
    "secret": "um-segredo-longo-e-aleatorio",
    "contentType": "json",
    "filters": [
        "service_invoice.issued_successfully",
        "service_invoice.issued_failed",
        "service_invoice.cancelled_successfully",
    ],
}

hook = client.webhooks.create(params)
print(hook.id, hook.status, hook.content_type)
```

- O SDK envia o corpo dentro de `{"webHook": ...}`. Você passa só os campos do webhook.
- **A API chama a URI na criação** para verificá-la: o endpoint precisa estar no ar e responder
  `2xx`, senão a criação falha com `InvalidRequestError`.
- Na criação, `status` é ignorado: o webhook nasce `Active`. Para desativá-lo, use `update`.
- A resposta da criação ecoa o `secret`. Não registre o objeto devolvido em log.
- Use um segredo longo e aleatório (por exemplo, `secrets.token_urlsafe(32)`). Ele é usado na
  [verificação da assinatura](../webhooks.md) e nunca aparece em logs nem em `repr`.

## Tipos de evento

```python
from nfeio import NfeClient

client = NfeClient()

for event_type in client.webhooks.event_types():
    print(event_type.id, event_type["description"])
```

Os ids são os valores aceitos em `filters`, como `service_invoice.issued_successfully`. A descrição
de cada evento está no [catálogo de eventos](../../../../documentacao/webhooks/catalogo-de-eventos.md).

## Alterar

`update` **substitui o webhook inteiro**, sem mesclar. Omitir `status` desativa o webhook. Busque,
altere e envie o objeto completo, **incluindo o segredo**: a consulta do webhook não devolve o
`secret`, então ele precisa vir da sua configuração.

```python
import os
from typing import Any

from nfeio import NfeClient

client = NfeClient()

atual: dict[str, Any] = client.webhooks.retrieve("ID_DO_WEBHOOK").to_dict()
atual["filters"].append("service_invoice.cancelled_failed")
atual["secret"] = os.environ.get("NFEIO_WEBHOOK_SECRET", "um-segredo-longo-e-aleatorio")
hook = client.webhooks.update("ID_DO_WEBHOOK", atual)
print(hook.status, hook["filters"])
```

## Testar e remover

```python
from nfeio import NfeClient

client = NfeClient()

client.webhooks.ping("ID_DO_WEBHOOK")  # a NFE.io envia uma entrega assinada com "action": "ping"

for hook in client.webhooks.list():
    print(hook.id, hook["uri"], hook.status)

client.webhooks.delete("ID_DO_WEBHOOK")
```

:::note Sem "apagar todos"
Não existe operação para remover todos os webhooks de uma vez, de propósito. Remova um por um.
:::

Propriedades tipadas de `Webhook`: `id`, `status`, `content_type`, `created_on` e `modified_on`.
`uri`, `filters` e os demais campos ficam no acesso por chave.

## Veja também

- [Webhooks (verificação)](../webhooks.md): Flask, FastAPI e Django.
- [Como cadastrar, consultar, listar, editar e excluir webhooks](../../../../documentacao/webhooks/como-cadastrar-consultar-listar-editar-e-excluir.md).