Product
Mesma API, novos truques: receba notificações de eventos no momento certo com webhooks
Tivemos algumas ideias enquanto trabalhávamos nesta atualização da API. Talvez você também tenha pensado nisso:
- Os webhooks são fantásticos! Todo mundo deveria usá-los.
- Extrair dados de envio diretamente das minhas mensagens economiza tempo.
Sinceramente, a API de webhooks do Mailgun já existe há muito tempo. Mas, com essa atualização, você tem mais opções para se comunicar com a gente e ver os detalhes do que está acontecendo com suas mensagens.
Vamos conferir os detalhes.
O que há de novo?
Então, sobre o que é essa atualização?
O Mailgun pode ajudar você a receber notificações no momento certo para ver quando algo acontece com a sua mensagem. Você tem a opção de usar o polling de eventos por meio da Events API, ou permitir que nós enviemos eventos a você por meio da API de webhooks. Esses alertas contêm os mesmos dados da API de eventos e são enviados para sua URL/URLs por HTTP POST.
Agora, você tem:
- Payload “Application/JSON”
- Até três URLs por evento
- Dados sobre os seguintes tipos de eventos:
- opened – sempre que um usuário abrir uma de suas mensagens
- clicked – sempre que um usuário clicar em um link nas suas mensagens
- unsubscribed – quando um usuário cancelar a inscrição, seja de todas as mensagens, de uma tag específica ou de uma lista de e-mails
- complained – quando um usuário denunciar um de seus e-mails como spam. Observe que nem todos os ESPs fornecem esse feedback.
- delivered – quando o servidor de e-mail do destinatário responder que aceitou a mensagem.
- permanent_fail – há vários motivos pelos quais o Mailgun para de tentar entregar mensagens e as descarta, incluindo devoluções definitivas, mensagens que atingiram o limite de tentativas, endereços com cancelamento de inscrição/devolução/reclamação anterior ou endereços rejeitados por um ESP.
- temporary_fail – quando uma mensagem for temporariamente rejeitada por um ESP
O lado bom disso é que o código da sua lógica de negócios pode ser usado para ambas as opções. A diferença está em como você se conecta ao Mailgun. E, como cada evento tem seu próprio ID exclusivo, se por algum motivo seu endpoint http cair, você poderá facilmente extrair os eventos e organizá-los usando esse ID exclusivo. Naturalmente, sempre recomendamos gerenciar webhooks de forma assíncrona para que picos de eventos não sejam um problema.
Como posso usar a API?
Agora vamos ver como configurar um domínio com o webhook “clicked”. É, na verdade, um processo de uma etapa que você pode concluir configurando uma ou mais URLs usando curl ou a sua linguagem de programação preferida pela nossa API HTTP.
Por exemplo, usando o comando curl:
curl -s --user ‘api:YOUR_API_KEY’
https://api.mailgun.net/v3/domains/YOUR_DOMAIN_NAME/webhooks
-X POST
-F id=clicked
-F url="https://api.your.domain.com/v1/mg/clicked"
-F url="https://api.your.domain.com/v2/mg/clicked"
-F url="https://api.partner.com/v1/you/clicked"
Aqui, "id" deve ser o nome do webhook (apenas um webhook por solicitação) e "url" deve indicar a sua URL (até três URLs por solicitação).
E a mensagem de resposta:
{
"message": "Webhook has been created",
"webhook": {
"urls": [
"https://api.your.domain.com/v1/mg/clicked",
"https://api.your.domain.com/v2/mg/clicked",
"https://api.partner.com/v1/you/clicked"
]
}
}
Os dados recebidos na sua URL/URLs devem ser:
{
“signature”:
{
"timestamp": "1529006854",
"token": "a8ce0edb2dd8301dee6c2405235584e45aa91d1e9f979f3de0",
"signature": "d2271d12299f6592d9d44cd9d250f0704e4674c30d79d07c47a66f95ce71cf55"
}
“event-data”:
{
"timestamp": 1529006854.329574,
"id": "DACSsAdVSeGpLid7TN03WA",
"event": "delivered",
"tags": [...],
"user-variables": {...},
"message": {
"headers": {
"message-id": "20180618211821.example.org"
}
},
…
}
}
A parte "event-data" é a mesma que a Events API retorna e contém: carimbo de data/hora do evento, ID exclusivo do evento, nome do evento, message-id, suas tags e variáveis etc. Como prática recomendada, não se esqueça de verificar a parte "signature" (veja aqui como fazer).
E é isso. Fácil, não é?
Posso enviar eventos para vários endpoints?
Sim, você pode! Se precisar migrar sua aplicação para uma nova versão ou enviar eventos para o site do seu parceiro, isso pode ser feito para até três endpoints.
Se quiser ver como o seu evento se parece ou tiver alguma dúvida para a nossa equipe de suporte, é fácil configurar um webhook com uma URL temporária para o nosso request bin em http://bin.mailgun.net e consumir eventos ao mesmo tempo.
Veja o que acontece ao usar também uma API de teste com o seguinte comando curl:
curl -s --user ‘api:YOUR_API_KEY’ \
https://api.mailgun.net/v3/domains/YOUR_DOMAIN_NAME/webhooks/HOOK_NAME/test \
-X PUT \
-F url=YOUR_URL
Aqui, "url" é a sua URL (uma por solicitação) e "HOOK_NAME" é o nome de um webhook (veja a lista acima – um por solicitação também).
E a mensagem de resposta:
{
"code" : null,
"message": "{\"message\":\"Post received. Thanks!\"
}
Aqui, "code" indica o código HTTP recebido do seu lado (nulo significa 200 OK) e "message" mostra o corpo HTTP recebido do seu lado ou a mensagem de erro
Sou um usuário do Mailgun, posso migrar facilmente para a nova API?
Sim. E todos os webhooks legados precisarão ser migrados para essa nova versão. O endpoint legado da API de webhooks tornou-se somente leitura a partir de 15 de abril de 2023, concluindo um processo de descontinuação iniciado em março de 2022.
As atualizações de produtos são importantes e, por sermos uma empresa de e-mail, somos muito bons em enviar atualizações para manter você por dentro das novidades. Quer explorar o porquê e o como por trás das nossas ações? Não se esqueça de assinar a nossa newsletter para receber mais conteúdos como este.
