Skip to main content
API reference

Webhooks

Endpoints that receive events, deliveries, replay and secret rotation.

List webhooks

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

Query parameters

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

Response 200

webhooksarray<object>required
Lista de webhooks cadastrados na organização

Create webhook

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

Request body

urlstring (uri)required
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+ itensrequired
Eventos aos quais o webhook deve se inscrever
descriptionstring≤ 500
Descrição opcional do webhook

Response 201

idstring (uuid)required
Identificador do webhook
urlstringrequired
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">required
Eventos aos quais o webhook está inscrito
status"active" | "paused" | "disabled"required
Status atual do webhook (active, paused ou disabled)
descriptionstringrequired
Descrição informada pelo usuário para o webhook
createdAtstring (date-time)required
Data e hora de criação do webhook
secretstring≥ 1required
Segredo usado para assinar os payloads enviados, exibido uma única vez

Get webhook

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

Path parameters

idstringrequired
Identificador do webhook

Response 200

idstring (uuid)required
Identificador do webhook
urlstringrequired
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">required
Eventos aos quais o webhook está inscrito
status"active" | "paused" | "disabled"required
Status atual do webhook (active, paused ou disabled)
descriptionstringrequired
Descrição informada pelo usuário para o webhook
createdAtstring (date-time)required
Data e hora de criação do webhook
metrics7dobject
Saúde das entregas do webhook nos últimos 7 dias
metrics7d.deliveredintegermín. 0máx. 9007199254740991required
Entregas com sucesso nos últimos 7 dias
metrics7d.failedintegermín. 0máx. 9007199254740991required
Entregas que falharam de vez (failed ou exhausted) nos últimos 7 dias
metrics7d.successRatenumbermín. 0máx. 100required
Sucesso ÷ (sucesso + falha), em %; null sem entregas concluídas
metrics7d.p95Msintegermín. 0máx. 9007199254740991required
Percentil 95 da duração das tentativas, em ms; null sem medição
metrics7d.lastDeliveryAtstring (date-time)required
Última tentativa de entrega no período
metrics7d.lastStatusintegermín. -9007199254740991máx. 9007199254740991required
Status HTTP da última tentativa que recebeu resposta
retryPolicyobject
Política de repetição aplicada às entregas
retryPolicy.maxAttemptsintegermín. 0máx. 9007199254740991required
Tentativas antes de desistir da entrega
retryPolicy.backoffBaseMsintegermín. 0máx. 9007199254740991required
Espera da primeira repetição, em ms
retryPolicy.backoffMaxMsintegermín. 0máx. 9007199254740991required
Espera máxima entre repetições, em ms
secretstringrequired
Segredo de assinatura completo (quando disponível)
secretPreviewstringrequired
Prévia truncada do segredo, para exibição segura

Update webhook

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

Path parameters

idstringrequired
Identificador do webhook

Request body

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

Response 200

idstring (uuid)required
Identificador do webhook
urlstringrequired
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">required
Eventos aos quais o webhook está inscrito
status"active" | "paused" | "disabled"required
Status atual do webhook (active, paused ou disabled)
descriptionstringrequired
Descrição informada pelo usuário para o webhook
createdAtstring (date-time)required
Data e hora de criação do webhook
metrics7dobject
Saúde das entregas do webhook nos últimos 7 dias
metrics7d.deliveredintegermín. 0máx. 9007199254740991required
Entregas com sucesso nos últimos 7 dias
metrics7d.failedintegermín. 0máx. 9007199254740991required
Entregas que falharam de vez (failed ou exhausted) nos últimos 7 dias
metrics7d.successRatenumbermín. 0máx. 100required
Sucesso ÷ (sucesso + falha), em %; null sem entregas concluídas
metrics7d.p95Msintegermín. 0máx. 9007199254740991required
Percentil 95 da duração das tentativas, em ms; null sem medição
metrics7d.lastDeliveryAtstring (date-time)required
Última tentativa de entrega no período
metrics7d.lastStatusintegermín. -9007199254740991máx. 9007199254740991required
Status HTTP da última tentativa que recebeu resposta
retryPolicyobject
Política de repetição aplicada às entregas
retryPolicy.maxAttemptsintegermín. 0máx. 9007199254740991required
Tentativas antes de desistir da entrega
retryPolicy.backoffBaseMsintegermín. 0máx. 9007199254740991required
Espera da primeira repetição, em ms
retryPolicy.backoffMaxMsintegermín. 0máx. 9007199254740991required
Espera máxima entre repetições, em ms
secretstringrequired
Segredo de assinatura completo (quando disponível)
secretPreviewstringrequired
Prévia truncada do segredo, para exibição segura

Pause or resume webhook

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

Path parameters

idstringrequired
Identificador do webhook

Request body

status"active" | "paused"required
Novo status do webhook (ativo ou pausado)

Delete webhook

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

Path parameters

idstringrequired
Identificador do webhook

Send a test event

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

Path parameters

idstringrequired
Identificador do webhook

Response 200

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

List deliveries

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

Path parameters

idstringrequired
Identificador do webhook

Query parameters

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

Response 200

deliveriesarray<object>required
Lista de tentativas de entrega do webhook, da mais recente para a mais antiga
nextCursorstringrequired
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. 9007199254740991required
Total de itens que batem com os filtros
pagination.pageintegermín. 0máx. 9007199254740991required
Página atual (começa em 1)
pagination.limitintegermín. 0máx. 9007199254740991required
Itens por página
pagination.totalPagesintegermín. 0máx. 9007199254740991required
Quantidade de páginas
pagination.totalIsEstimatebooleanrequired
true quando o total passa de 10000 e vem de estimativa

Deliveries of an email

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

Path parameters

idstring (uuid)required
Identificador do e-mail

Response 200

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

Get delivery

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

Path parameters

idstringrequired
Identificador do webhook
deliveryIdstring (uuid)required
Identificador da entrega

Response 200

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

Replay delivery

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

Path parameters

idstringrequired
Identificador do webhook
deliveryIdstring (uuid)required
Identificador da entrega

Response 202

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

Rotate secret

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

Path parameters

idstringrequired
Identificador do webhook