Saltar al contenido principal
Referencia de la API

Webhooks

Endpoints que reciben eventos, entregas, reenvío y rotación de secreto.

Listar webhooks

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

Parámetros de consulta

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

Respuesta 200

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

Crear webhook

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

Cuerpo de la solicitud

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

Respuesta 201

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

Obtener webhook

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

Parámetros de ruta

idstringobligatorio
Identificador do webhook

Respuesta 200

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

Actualizar webhook

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

Parámetros de ruta

idstringobligatorio
Identificador do webhook

Cuerpo de la solicitud

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

Respuesta 200

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

Pausar o reactivar webhook

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

Parámetros de ruta

idstringobligatorio
Identificador do webhook

Cuerpo de la solicitud

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

Eliminar webhook

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

Parámetros de ruta

idstringobligatorio
Identificador do webhook

Enviar prueba

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

Parámetros de ruta

idstringobligatorio
Identificador do webhook

Respuesta 200

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

Listar entregas

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

Parámetros de ruta

idstringobligatorio
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

Respuesta 200

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

Entregas de un email

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

Parámetros de ruta

idstring (uuid)obligatorio
Identificador do e-mail

Respuesta 200

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

Obtener entrega

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

Parámetros de ruta

idstringobligatorio
Identificador do webhook
deliveryIdstring (uuid)obligatorio
Identificador da entrega

Respuesta 200

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

Reenviar entrega

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

Parámetros de ruta

idstringobligatorio
Identificador do webhook
deliveryIdstring (uuid)obligatorio
Identificador da entrega

Respuesta 202

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

Rotar secreto

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

Parámetros de ruta

idstringobligatorio
Identificador do webhook