Pular para o conteúdo principal
Referência da API

Webhooks

Endpoints que recebem eventos, entregas, reenvio e rotação de segredo.

Listar webhooks

GEThttps://api.coffeemail.com.br/v1/product/webhooks200

Parâmetros de consulta

statusstring
Filtra webhooks pelo status (active, paused ou disabled)

Resposta 200

webhooksarray<object>obrigatório
Lista de webhooks cadastrados na organização

Criar webhook

POSThttps://api.coffeemail.com.br/v1/product/webhooks201

Corpo da requisição

urlstring (uri)obrigatório
URL de destino que receberá os eventos
eventsarray<"email.queued" | "email.processing" | "email.sent" | "email.delivered" | "email.delivery_delayed" | "email.opened" | "email.clicked" | "email.bounced" | "email.complained" | "email.failed" | "email.suppressed" | "email.scheduled" | "email.cancelled" | "email.unsubscribed" | "billing.plan_changed">1+ itensobrigatório
Eventos aos quais o webhook deve se inscrever
descriptionstring≤ 500
Descrição opcional do webhook

Resposta 201

idstring (uuid)obrigatório
Identificador do webhook
urlstringobrigatório
URL de destino que recebe os eventos
eventsarray<"email.queued" | "email.processing" | "email.sent" | "email.delivered" | "email.delivery_delayed" | "email.opened" | "email.clicked" | "email.bounced" | "email.complained" | "email.failed" | "email.suppressed" | "email.scheduled" | "email.cancelled" | "email.unsubscribed" | "billing.plan_changed">obrigatório
Eventos aos quais o webhook está inscrito
status"active" | "paused" | "disabled"obrigatório
Status atual do webhook (active, paused ou disabled)
descriptionstringobrigatório
Descrição informada pelo usuário para o webhook
createdAtstring (date-time)obrigatório
Data e hora de criação do webhook
secretstring≥ 1obrigatório
Segredo usado para assinar os payloads enviados, exibido uma única vez

Obter webhook

GEThttps://api.coffeemail.com.br/v1/product/webhooks/{id}200

Parâmetros do caminho

idstringobrigatório
Identificador do webhook

Resposta 200

idstring (uuid)obrigatório
Identificador do webhook
urlstringobrigatório
URL de destino que recebe os eventos
eventsarray<"email.queued" | "email.processing" | "email.sent" | "email.delivered" | "email.delivery_delayed" | "email.opened" | "email.clicked" | "email.bounced" | "email.complained" | "email.failed" | "email.suppressed" | "email.scheduled" | "email.cancelled" | "email.unsubscribed" | "billing.plan_changed">obrigatório
Eventos aos quais o webhook está inscrito
status"active" | "paused" | "disabled"obrigatório
Status atual do webhook (active, paused ou disabled)
descriptionstringobrigatório
Descrição informada pelo usuário para o webhook
createdAtstring (date-time)obrigatório
Data e hora de criação do webhook
metrics7dobject
Saúde das entregas do webhook nos últimos 7 dias
metrics7d.deliveredintegermín. 0máx. 9007199254740991obrigatório
Entregas com sucesso nos últimos 7 dias
metrics7d.failedintegermín. 0máx. 9007199254740991obrigatório
Entregas que falharam de vez (failed ou exhausted) nos últimos 7 dias
metrics7d.successRatenumbermín. 0máx. 100obrigatório
Sucesso ÷ (sucesso + falha), em %; null sem entregas concluídas
metrics7d.p95Msintegermín. 0máx. 9007199254740991obrigatório
Percentil 95 da duração das tentativas, em ms; null sem medição
metrics7d.lastDeliveryAtstring (date-time)obrigatório
Última tentativa de entrega no período
metrics7d.lastStatusintegermín. -9007199254740991máx. 9007199254740991obrigatório
Status HTTP da última tentativa que recebeu resposta
retryPolicyobject
Política de repetição aplicada às entregas
retryPolicy.maxAttemptsintegermín. 0máx. 9007199254740991obrigatório
Tentativas antes de desistir da entrega
retryPolicy.backoffBaseMsintegermín. 0máx. 9007199254740991obrigatório
Espera da primeira repetição, em ms
retryPolicy.backoffMaxMsintegermín. 0máx. 9007199254740991obrigatório
Espera máxima entre repetições, em ms
secretstringobrigatório
Segredo de assinatura completo (quando disponível)
secretPreviewstringobrigatório
Prévia truncada do segredo, para exibição segura

Atualizar webhook

PUThttps://api.coffeemail.com.br/v1/product/webhooks/{id}200

Parâmetros do caminho

idstringobrigatório
Identificador do webhook

Corpo da requisição

urlstring (uri)
Nova URL de destino que receberá os eventos
eventsarray<"email.queued" | "email.processing" | "email.sent" | "email.delivered" | "email.delivery_delayed" | "email.opened" | "email.clicked" | "email.bounced" | "email.complained" | "email.failed" | "email.suppressed" | "email.scheduled" | "email.cancelled" | "email.unsubscribed" | "billing.plan_changed">1+ itens
Novos eventos aos quais o webhook deve se inscrever
descriptionstring≤ 500
Nova descrição do webhook

Resposta 200

idstring (uuid)obrigatório
Identificador do webhook
urlstringobrigatório
URL de destino que recebe os eventos
eventsarray<"email.queued" | "email.processing" | "email.sent" | "email.delivered" | "email.delivery_delayed" | "email.opened" | "email.clicked" | "email.bounced" | "email.complained" | "email.failed" | "email.suppressed" | "email.scheduled" | "email.cancelled" | "email.unsubscribed" | "billing.plan_changed">obrigatório
Eventos aos quais o webhook está inscrito
status"active" | "paused" | "disabled"obrigatório
Status atual do webhook (active, paused ou disabled)
descriptionstringobrigatório
Descrição informada pelo usuário para o webhook
createdAtstring (date-time)obrigatório
Data e hora de criação do webhook
metrics7dobject
Saúde das entregas do webhook nos últimos 7 dias
metrics7d.deliveredintegermín. 0máx. 9007199254740991obrigatório
Entregas com sucesso nos últimos 7 dias
metrics7d.failedintegermín. 0máx. 9007199254740991obrigatório
Entregas que falharam de vez (failed ou exhausted) nos últimos 7 dias
metrics7d.successRatenumbermín. 0máx. 100obrigatório
Sucesso ÷ (sucesso + falha), em %; null sem entregas concluídas
metrics7d.p95Msintegermín. 0máx. 9007199254740991obrigatório
Percentil 95 da duração das tentativas, em ms; null sem medição
metrics7d.lastDeliveryAtstring (date-time)obrigatório
Última tentativa de entrega no período
metrics7d.lastStatusintegermín. -9007199254740991máx. 9007199254740991obrigatório
Status HTTP da última tentativa que recebeu resposta
retryPolicyobject
Política de repetição aplicada às entregas
retryPolicy.maxAttemptsintegermín. 0máx. 9007199254740991obrigatório
Tentativas antes de desistir da entrega
retryPolicy.backoffBaseMsintegermín. 0máx. 9007199254740991obrigatório
Espera da primeira repetição, em ms
retryPolicy.backoffMaxMsintegermín. 0máx. 9007199254740991obrigatório
Espera máxima entre repetições, em ms
secretstringobrigatório
Segredo de assinatura completo (quando disponível)
secretPreviewstringobrigatório
Prévia truncada do segredo, para exibição segura

Pausar ou reativar webhook

PATCHhttps://api.coffeemail.com.br/v1/product/webhooks/{id}200

Parâmetros do caminho

idstringobrigatório
Identificador do webhook

Corpo da requisição

status"active" | "paused"obrigatório
Novo status do webhook (ativo ou pausado)

Excluir webhook

DELETEhttps://api.coffeemail.com.br/v1/product/webhooks/{id}200

Parâmetros do caminho

idstringobrigatório
Identificador do webhook

Disparar teste

POSThttps://api.coffeemail.com.br/v1/product/webhooks/{id}/test200

Parâmetros do caminho

idstringobrigatório
Identificador do webhook

Resposta 200

status"success" | "failed"obrigatório
Resultado do envio de teste
statusCodeintegermín. -9007199254740991máx. 9007199254740991obrigatório
Status HTTP retornado pelo endpoint de destino
latencyMsintegermín. 0máx. 9007199254740991obrigatório
Tempo total do disparo de teste, em milissegundos
bodystringobrigatório
Primeiro 1 KB do corpo da resposta retornada pelo endpoint de destino
errorstringobrigatório
Mensagem de erro, caso o envio de teste tenha falhado

Listar entregas

GEThttps://api.coffeemail.com.br/v1/product/webhooks/{id}/deliveries200

Parâmetros do caminho

idstringobrigatório
Identificador do webhook

Parâmetros de consulta

eventTypestring
Filtra entregas por tipo de evento
status"pending" | "success" | "failed" | "exhausted"
Filtra entregas pelo status atual
fromstring (date-time)
Data inicial do período de busca
tostring (date-time)
Data final do período de busca
limitintegermín. 0máx. 200
Quantidade máxima de entregas retornadas
pageintegermín. 0máx. 100000
Página numerada (começa em 1). Ignorada quando `after` é enviado
afterstring≥ 1≤ 512
Cursor opaco de paginação: envie o nextCursor da página anterior para receber as entregas mais antigas que ela. Cursor inválido ou adulterado retorna 400

Resposta 200

deliveriesarray<object>obrigatório
Lista de tentativas de entrega do webhook, da mais recente para a mais antiga
nextCursorstringobrigatório
Cursor da próxima página (use em after); null quando não há mais entregas
paginationobject
Paginação numerada. Ausente quando a consulta usa cursor (`after`)
pagination.totalintegermín. 0máx. 9007199254740991obrigatório
Total de itens que batem com os filtros
pagination.pageintegermín. 0máx. 9007199254740991obrigatório
Página atual (começa em 1)
pagination.limitintegermín. 0máx. 9007199254740991obrigatório
Itens por página
pagination.totalPagesintegermín. 0máx. 9007199254740991obrigatório
Quantidade de páginas
pagination.totalIsEstimatebooleanobrigatório
true quando o total passa de 10000 e vem de estimativa

Entregas de um email

GEThttps://api.coffeemail.com.br/v1/product/emails/{id}/webhook-deliveries200

Parâmetros do caminho

idstring (uuid)obrigatório
Identificador do e-mail

Resposta 200

deliveriesarray<object>obrigatório
Entregas de webhook disparadas por este e-mail, da mais recente para a mais antiga

Obter entrega

GEThttps://api.coffeemail.com.br/v1/product/webhooks/{id}/deliveries/{deliveryId}200

Parâmetros do caminho

idstringobrigatório
Identificador do webhook
deliveryIdstring (uuid)obrigatório
Identificador da entrega

Resposta 200

idstring (uuid)obrigatório
Identificador da tentativa de entrega
webhookIdstring (uuid)obrigatório
Identificador do webhook associado
emailEventIdstring (uuid)obrigatório
Evento de e-mail que originou a entrega
eventTypestringobrigatório
Tipo de evento disparado (ex: email.delivered)
responseStatusintegermín. -9007199254740991máx. 9007199254740991obrigatório
Status HTTP retornado pelo endpoint de destino
responseBodystringobrigatório
Corpo da resposta retornada pelo endpoint de destino
attemptsintegermín. -9007199254740991máx. 9007199254740991obrigatório
Quantidade de tentativas de envio já realizadas
durationMsintegermín. 0máx. 9007199254740991
Duração da última tentativa, em ms; null para entregas antigas
lastErrorstringobrigatório
Mensagem do último erro ocorrido no envio
statusstringobrigatório
Status atual da entrega (pending, success, failed ou exhausted)
nextRunAtstring (date-time)obrigatório
Data e hora da próxima tentativa de reenvio
createdAtstring (date-time)obrigatório
Data e hora em que a entrega foi criada
requestPayloadstringobrigatório
Corpo JSON enviado ao endpoint de destino

Reenviar entrega

POSThttps://api.coffeemail.com.br/v1/product/webhooks/{id}/deliveries/{deliveryId}/replay202

Parâmetros do caminho

idstringobrigatório
Identificador do webhook
deliveryIdstring (uuid)obrigatório
Identificador da entrega

Resposta 202

idstring (uuid)obrigatório
Identificador da tentativa de entrega
webhookIdstring (uuid)obrigatório
Identificador do webhook associado
emailEventIdstring (uuid)obrigatório
Evento de e-mail que originou a entrega
eventTypestringobrigatório
Tipo de evento disparado (ex: email.delivered)
responseStatusintegermín. -9007199254740991máx. 9007199254740991obrigatório
Status HTTP retornado pelo endpoint de destino
responseBodystringobrigatório
Corpo da resposta retornada pelo endpoint de destino
attemptsintegermín. -9007199254740991máx. 9007199254740991obrigatório
Quantidade de tentativas de envio já realizadas
durationMsintegermín. 0máx. 9007199254740991
Duração da última tentativa, em ms; null para entregas antigas
lastErrorstringobrigatório
Mensagem do último erro ocorrido no envio
statusstringobrigatório
Status atual da entrega (pending, success, failed ou exhausted)
nextRunAtstring (date-time)obrigatório
Data e hora da próxima tentativa de reenvio
createdAtstring (date-time)obrigatório
Data e hora em que a entrega foi criada
requestPayloadstringobrigatório
Corpo JSON enviado ao endpoint de destino

Rotacionar segredo

POSThttps://api.coffeemail.com.br/v1/product/webhooks/{id}/rotate-secret200

Parâmetros do caminho

idstringobrigatório
Identificador do webhook