Visão geral dos webhooks

O Sursa registra um evento a cada alteração importante: um cartão é publicado, verificado ou arquivado, um comunicado é lido, uma pergunta fica sem resposta. Você pode receber os eventos de duas formas e usar as duas juntas:

	Webhooks	Feed de eventos
Como	O Sursa envia cada evento para o seu endereço HTTPS assim que ele acontece.	Você lê `GET /v1/webhook-events` quando quiser.
Latência	Segundos.	Com a frequência com que você consulta.
Requisitos	Um receptor HTTPS público.	Só uma chave de API com a função `admin` e o escopo `webhooks:manage`.
Indicado para	Reagir a alterações: notificar, sincronizar, iniciar um fluxo de trabalho.	Jobs em lote, recuperar o atraso depois de uma indisponibilidade, reconciliação.

Os dois trazem os mesmos eventos, com os mesmos IDs. Todo evento fica no feed por 30 dias, haja ou não algum webhook inscrito nele.

O evento

{
  "id": "evt_0123456789abcdef0123456789abcdef",
  "type": "card.updated",
  "created_at": "2026-10-24T10:00:03Z",
  "org_id": 1,
  "api_version": "1.60.0",
  "sequence": 1042,
  "object": {"type": "card", "id": "3f2c9a7e-5b1d-4c8e-9f0a-1b2c3d4e5f60"},
  "payload": "full",
  "data": {
    "card": {"id": "3f2c9a7e-5b1d-4c8e-9f0a-1b2c3d4e5f60", "title": "Refund policy", "collection": "support", "version": 4},
    "actor_id": 7,
    "previous_attributes": {"title": "Refunds"}
  },
  "test": false
}

Campo	Significado
`id`	O ID do evento, `evt_` e 32 caracteres hexadecimais. É o mesmo em todas as tentativas de entrega e no feed.
`type`	O que aconteceu, no formato `<object>.<past-tense verb>`: `card.updated`, `access_request.resolved`.
`created_at`	Quando a alteração aconteceu, em UTC.
`api_version`	A versão da API cujo esquema `data` segue.
`object`	O tipo e o ID do objeto a que o evento se refere.
`data`	Os detalhes. O formato depende do tipo e está descrito no catálogo de eventos.
`data.previous_attributes`	Nos eventos `*.updated`: os valores anteriores dos campos que mudaram.
`sequence`, `payload`, `test`	Só nas entregas de webhooks: a posição na ordem do webhook, o modo de payload e se este é um evento de teste.

data contém só o que qualquer leitor do objeto poderia ver pela API. Ele nunca traz listas de acesso, as permissões de outras pessoas nem campos ocultos. Os motivos nos eventos são códigos neutros curtos, como no_hits, restricted ou index_failed.

Tipos de evento

Os eventos cobrem estas áreas:

Área	Exemplos
Cartões	`card.created`, `card.updated`, `card.published`, `card.archived`, `card.deleted`, `card.indexed`, `card.index_failed`
Verificação	`card.verified`, `card.unverified`, `verification.expired`, `verification.requested`
Estrutura	`collection.created`, `folder.updated`
Colaboração	`comment.created`, `draft.publish_requested`, `announcement.sent`, `announcement.read`
Respostas	`question.unanswered`, `question.feedback_created`, `access_request.created`
Pessoas e acesso	`user.created`, `user.deactivated`, `group.member_added`, `api_key.expiring`
Fontes e importação	`source.sync_completed`, `import.sync_completed`, `import.document_failed`
Jobs	`job.completed`, `job.failed`, `export.ready`
Webhooks	`webhook.endpoint_disabled`, `webhook.ping`

A lista completa, com o esquema e um exemplo de cada evento, está no catálogo de eventos da referência da API. GET /v1/webhooks/catalog retorna os tipos disponíveis na sua instalação.

Novos tipos de evento são acrescentados com o tempo, e os eventos existentes ganham campos. Os tipos de evento nunca são renomeados nem removidos. O seu receptor precisa ignorar os tipos e os campos que não conhece.

Quem recebe o quê

Um webhook só recebe um evento se o objeto do evento estiver visível para ele, da mesma forma que para uma chave de API: pela função, pelo perfil de dados e pelas coleções dele. Um webhook limitado à coleção support nunca recebe eventos sobre cartões de finance. Os eventos sobre pessoas, chaves, fontes, importações, jobs, exportações, faturamento, aplicativos e os próprios webhooks vão só para webhooks com a função admin.

Dentro disso, cada webhook escolhe os seus eventos:

por tipo, com máscaras: card.* para todos os eventos de cartões, * para todos os eventos;
por coleção e por etiqueta, nos eventos de cartões.

O modo de payload de um webhook é full (o evento com data, o padrão) ou thin (o evento sem data: o seu receptor lê o objeto pela API com a própria chave e sempre vê o estado atual dele).

A entrega em resumo

Um POST HTTPS com o evento em JSON, assinado com o segredo do webhook em dois formatos: Standard Webhooks (webhook-signature) e o anterior X-KB-Signature.
Qualquer resposta 2xx em até 10 segundos é um sucesso.
Uma falha ganha novas tentativas por quase três dias, com pausas cada vez maiores. O Retry-After de uma resposta 429 ou 503 é respeitado; 410 desativa o webhook; 10 falhas seguidas o pausam até que ele seja retomado.
As entregas a um webhook são enviadas estritamente em ordem. Um webhook lento não atrasa os outros.
O mesmo evento pode chegar mais de uma vez: descarte as duplicatas pelo webhook-id.

Receber webhooks mostra passo a passo um receptor completo, com a verificação de assinaturas em Node.js, Python e Go.

Gerenciar webhooks

Tarefa	Endpoint
Criar um webhook e receber o segredo dele	`POST /v1/webhooks`
Alterar o endereço, os eventos ou o estado	`PATCH /v1/webhooks/{webhook_id}`
Enviar um evento de teste	`POST /v1/webhooks/{webhook_id}/test`
Rotacionar o segredo	`POST /v1/webhooks/{webhook_id}/rotate-secret`
Retomar um webhook pausado	`POST /v1/webhooks/{webhook_id}/resume`
Ver as entregas e as respostas	`GET /v1/webhooks/{webhook_id}/deliveries`
Enviar uma entrega de novo	`POST /v1/webhooks/{webhook_id}/deliveries/{delivery_id}/redeliver`

Gerenciar webhooks exige uma chave com a função admin e o escopo webhooks:manage, ou um administrador na interface de administração. Uma organização pode ter até 20 webhooks. Os webhooks fazem parte do plano da organização; sem eles, estes endpoints respondem 403 com o código webhooks.feature_disabled.