Referência da API
Webhooks
Endpoints que recebem eventos, entregas, reenvio e rotação de segredo.
Listar webhooks
GET
https://api.coffeemail.com.br/v1/product/webhooks200Parâ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
POST
https://api.coffeemail.com.br/v1/product/webhooks201Corpo 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
GET
https://api.coffeemail.com.br/v1/product/webhooks/{id}200Parâ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
PUT
https://api.coffeemail.com.br/v1/product/webhooks/{id}200Parâ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
PATCH
https://api.coffeemail.com.br/v1/product/webhooks/{id}200Parâ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
DELETE
https://api.coffeemail.com.br/v1/product/webhooks/{id}200Parâmetros do caminho
idstringobrigatório- Identificador do webhook
Disparar teste
POST
https://api.coffeemail.com.br/v1/product/webhooks/{id}/test200Parâ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
GET
https://api.coffeemail.com.br/v1/product/webhooks/{id}/deliveries200Parâ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
GET
https://api.coffeemail.com.br/v1/product/emails/{id}/webhook-deliveries200Parâ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
GET
https://api.coffeemail.com.br/v1/product/webhooks/{id}/deliveries/{deliveryId}200Parâ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
POST
https://api.coffeemail.com.br/v1/product/webhooks/{id}/deliveries/{deliveryId}/replay202Parâ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
POST
https://api.coffeemail.com.br/v1/product/webhooks/{id}/rotate-secret200Parâmetros do caminho
idstringobrigatório- Identificador do webhook