Webhooks

Assinaturas de saída para os eventos da plataforma, o segredo de assinatura delas e as tentativas de entrega que produziram. Onze tools — o maior recurso.

Veja o modelo Webhook, o modelo WebhookDelivery e Segurança de webhooks para a validação da assinatura HMAC.

---

webhooks_list

Leitura · escopo inbox/webhooks · permissão webhooks.list · GET /webhooks

Lista as assinaturas de webhook. Segredos de assinatura nunca são retornados.

Parâmetro	Tipo	Descrição
cursor	string	Cursor opaco de uma página anterior.
limit	integer	Tamanho da página, padrão 25, máximo 100.
sort	string	Chaves de ordenação, prefixo - para descendente.
status	active | inactive	Filtra por status.
inbox_id	string (uuid)	Apenas assinaturas restritas a esta inbox.
external_id	string	Filtra pelo id no seu sistema.
created_at_gte / created_at_lte	string	Intervalo ISO 8601 sobre created_at.

webhooks_get

Leitura · escopo inbox/webhooks · permissão webhooks.show · GET /webhooks/{id}

Busca um webhook por id interno ou external_id.

Parâmetro	Tipo	Descrição
id obrigatório	string	Id interno ou external_id.

webhooks_create

Escrita · escopo inbox/webhooks + write · permissão webhooks.create · POST /webhooks

Cria uma assinatura de webhook. A resposta carrega o signing_secret em texto claro exatamente uma vez — mostre-o ao usuário imediatamente, ele não pode ser lido de novo.

Parâmetro	Tipo	Descrição
label obrigatório	string	Nome de exibição, 1–120 caracteres.
url obrigatório	string	URL de destino.
external_id	string	Id do registro no seu sistema.
inbox_id	string (uuid) | null	Restringe a assinatura a uma inbox; null significa o workspace inteiro.
subscribed_events	string[]	Slugs de evento a assinar.
auth	none | basic | bearer | header	Esquema de autenticação usado ao chamar o seu endpoint.
auth_basic_user	string	Usuário, para basic.
auth_basic_password	string	Senha, para basic.
auth_bearer_token	string	Token, para bearer.
auth_header_key	string	Nome do header, para header.
auth_header_value	string	Valor do header, para header.
signing_secret	string	Traga o seu próprio segredo (whsec_…); gerado quando omitido.
custom_metadata	object	JSON livre, de quem chama.
idempotency_key	string	Proteção contra replay, 8–255 caracteres.

webhooks_upsert

Escrita · escopo inbox/webhooks + write · permissão webhooks.create · PUT /webhooks

Cria ou atualiza um webhook, casado por id e depois external_id. Um bloco auth substitui o armazenado por inteiro; um signing_secret rotaciona o segredo e é devolvido uma vez.

Parâmetro	Tipo	Descrição
id	string (uuid)	Casa primeiro pelo id interno.
external_id	string	Chave de casamento no seu sistema.
label	string	Nome de exibição, 1–120 caracteres.
url	string	URL de destino.
inbox_id	string (uuid) | null	Restringe a uma inbox, ou null para o workspace.
subscribed_events	string[]	Slugs de evento a assinar.
auth	none | basic | bearer | header	Esquema de autenticação.
auth_basic_user	string	Usuário, para basic.
auth_basic_password	string	Senha, para basic.
auth_bearer_token	string	Token, para bearer.
auth_header_key	string	Nome do header, para header.
auth_header_value	string	Valor do header, para header.
signing_secret	string	Rotaciona o segredo; devolvido uma vez.
custom_metadata	object	JSON livre.
idempotency_key	string	Proteção contra replay.

webhooks_update

Escrita · escopo inbox/webhooks + write · permissão webhooks.update · PATCH /webhooks/{id}

Atualiza uma assinatura de webhook no lugar.

Parâmetro	Tipo	Descrição
id obrigatório	string	Id interno ou external_id.
label	string	Nome de exibição, 1–120 caracteres.
url	string	URL de destino.
external_id	string	Id no seu sistema.
inbox_id	string (uuid) | null	Restringe a uma inbox, ou null para o workspace.
subscribed_events	string[]	Slugs de evento a assinar.
auth	none | basic | bearer | header	Esquema de autenticação.
auth_basic_user	string	Usuário, para basic.
auth_basic_password	string	Senha, para basic.
auth_bearer_token	string	Token, para bearer.
auth_header_key	string	Nome do header, para header.
auth_header_value	string	Valor do header, para header.
custom_metadata	object	JSON livre.

webhooks_delete

Destrutiva · escopo inbox/webhooks + write · permissão webhooks.delete · DELETE /webhooks/{id}

Exclui (soft-delete) uma assinatura de webhook. As entregas pendentes param.

Parâmetro	Tipo	Descrição
id obrigatório	string	Id interno ou external_id.

webhooks_test

Destrutiva · escopo inbox/webhooks + write · permissão webhooks.test · POST /webhooks/{id}/test

Envia um webhook.ping sintético pelo caminho real de assinatura e retry, para você validar URL e autenticação. Responde 202.

Parâmetro	Tipo	Descrição
id obrigatório	string	Id interno ou external_id.
idempotency_key	string	Proteção contra replay, 8–255 caracteres.

webhooks_regenerate_secret

Destrutiva · escopo inbox/webhooks + write · permissão webhooks.rotate-secret · POST /webhooks/{id}/regenerate-secret

Rotaciona o segredo de assinatura. O novo é devolvido uma vez; o anterior continua validando durante a janela de carência.

Parâmetro	Tipo	Descrição
id obrigatório	string	Id interno ou external_id.
idempotency_key	string	Proteção contra replay, 8–255 caracteres.

webhooks_deliveries_list

Leitura · escopo inbox/webhooks · permissão webhooks.show · GET /webhooks/{id}/deliveries

Tentativas de entrega de um webhook, com status HTTP e número da tentativa.

Parâmetro	Tipo	Descrição
id obrigatório	string	Id interno ou external_id do webhook.
cursor	string	Cursor opaco de uma página anterior.
limit	integer	Tamanho da página, padrão 25, máximo 100.
sort	string	Chaves de ordenação, prefixo - para descendente.
status	pending | success | failed	Filtra por status da entrega.
attempt	integer	Filtra pelo número da tentativa.
response_status	integer	Filtra pelo status HTTP que o seu endpoint respondeu.
system_event_id	string (uuid)	Apenas entregas deste evento.
created_at_gte / created_at_lte	string	Intervalo ISO 8601 sobre created_at.

webhooks_deliveries_get

Leitura · escopo inbox/webhooks · permissão webhooks.show · GET /webhooks/{id}/deliveries/{delivery_id}

Busca uma tentativa de entrega, incluindo headers e corpos de requisição e resposta.

Parâmetro	Tipo	Descrição
id obrigatório	string	Id interno ou external_id do webhook.
delivery_id obrigatório	string (uuid)	Id da entrega.

webhooks_deliveries_replay

Destrutiva · escopo inbox/webhooks + write · permissão webhooks.replay · POST /webhooks/{id}/deliveries/{delivery_id}/replay

Reenvia uma entrega com assinatura nova. Responde 202.

Parâmetro	Tipo	Descrição
id obrigatório	string	Id interno ou external_id do webhook.
delivery_id obrigatório	string (uuid)	Id da entrega.
idempotency_key	string	Proteção contra replay, 8–255 caracteres.