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.

Métodos

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

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 e nunca aparece em logs nem em repr.

Tipos de evento

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.

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.

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

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")

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): Flask, FastAPI e Django.
• Como cadastrar, consultar, listar, editar e excluir webhooks.