Seu guia para usar webhooks

Você já sabe que um e-mail não é o tipo de coisa que se envia e esquece. Ao enviar uma mensagem, você quer saber como rastreá-la e resolver qualquer problema que possa surgir, não é? Afinal, saber o desempenho dos seus e-mails ajuda a manter sua reputação do remetente e suas taxas de entregabilidade. Ao direcionar um webhook para seu CRM favorito, sua equipe consegue ver métricas de engajamento relevantes com rapidez e facilidade, além de tomar decisões com base em informações atualizadas. Antes de detalharmos os casos de uso, vamos abordar os conceitos básicos sobre webhooks.

De forma simples, os webhooks são notificações que enviam dados de um evento para outro aplicativo depois que ele ocorre. Eles atuam como uma API reversa, em que, em vez de consultar um endpoint de API repetidamente em busca de atualizações, o webhook envia a atualização para você por meio de uma solicitação HTTP. Webhooks são uma maneira de os aplicativos comunicarem informações por meio de automação e callbacks HTTP definidos por quem usa – como mensagens SMS –, normalmente acionados por um evento como uma entrega de e-mail bem-sucedida ou uma notificação de devolução.

Em uma arquitetura orientada a eventos, isso se torna muito poderoso. Por exemplo, quando você fornece ao aplicativo do seu banco as informações de depósito direto e seu número de telefone, e ele envia uma mensagem SMS avisando que você acabou de receber um depósito, é um webhook que permite ao banco enviar essa mensagem de texto com atualizações relevantes.

Os webhooks são usados para criar notificações sobre eventos específicos. Como os webhooks baseiam-se em solicitações HTTP POST, eles são muito fáceis de usar. Além disso, os scripts de webhook podem ser escritos em praticamente qualquer linguagem de programação que você preferir, como curl, Ruby, Python, PHP, Java, C# e Go. Após a captura dos dados do webhook, eles podem ser armazenados em um banco de dados e usados para avaliar a eficácia das campanhas de e-mail ou enriquecer os perfis dos destinatários. Use-os em vários fluxos de trabalho, desde o registro de confirmações de pedido de e-commerce até a integração de eventos de pagamento do Stripe em tempo real ao seu backend.

Ao personalizar as métricas que o webhook retorna, você também pode obter dados mais granulares do que um painel nativo forneceria.

Então, como funciona um webhook?

Quando o evento ocorre, o site de origem faz uma solicitação HTTP POST a uma URL configurada pela equipe de desenvolvimento para receber o webhook. A equipe de desenvolvimento pode configurá-los para que eventos em um site ativem o comportamento em outro. Em seguida, os dados desse webhook podem ser enviados para a URL configurada como um payload de webhook nos formatos JSON ou XML. Veja as quatro etapas necessárias:

A primeira decisão da equipe de desenvolvimento ao estruturar o rastreamento e a resposta de e-mail é definir exatamente quais dados querem que retornem. Se a meta for saber quando os e-mails enviados estão sofrendo devoluções, a URL do usuário pode executar um script nos POSTs recebidos para capturar e salvar o endereço de e-mail devolvido em um banco de dados local. O mesmo script pode ser ampliado para capturar o nome dos destinatários, o assunto ou qualquer outro parâmetro fornecido pelo webhook.

Vamos começar analisando a solicitação POST do webhook, que pode ser codificada como: application/x-www-form-urlencoded para a maioria das mensagens e como multipart/form-data caso haja um anexo incluído na mensagem. O método da solicitação POST foi criado para pedir que um servidor da web aceite os dados incluídos no corpo da mensagem de solicitação para armazenamento.

Veja um exemplo de um HTTP POST feito pelo Mailgun para um URI no Runescope. Observe que o cabeçalho de tipo de conteúdo está definido como application/x-www-form-urlencoded:

                                

                                    ACCEPT: */* 
ACCEPT-ENCODING: GZIP 
CONNECTION: CLOSE 
CONTENT-LENGTH: 1325 
CONTENT-TYPE: APPLICATION/X-WWW-FORM-URLENCODED 
HOST: 
USER-AGENT: MAILGUN/TREQ-0.2.
                                
                            

O corpo da mensagem contém parâmetros armazenados como pares de chave-valor. (Falaremos com mais detalhes sobre os dados postados na seção a seguir.) Como os dados são codificados, eles parecerão confusos à primeira vista. Veja como o corpo decodificado normalmente fica:

                                

                                    DOMAIN: BEATNIKZ.NET
EVENT: DELIVERED
MESSAGE-HEADERS: [["RECEIVED", "BY LUNA.MAILGUN.NET WITH HTTP; WED, 07 JAN 2015 00:44:03 +0000"], ["MIME-VERSION", "1.0"], ["CONTENT-TYPE", ["TEXT/PLAIN", {"CHARSET": "ASCII"}]], ["SUBJECT", "HELLO"], ["FROM", "TAG TEST "], ["TO", "MGBOX01@GMAIL.COM"], ["X-MAILGUN-TAG", "WEB APP SEPTEMBER NEWSLETTER"], ["X-MAILGUN-TAG", "NEWSLETTERS"], ["MESSAGE-ID", ""], ["X-MAILGUN-SID", "WYI3NGU3NYISICJTZ2JVEDAXQGDTYWLSLMNVBSISICI0MGRKIL0="], ["DATE", "WED, 07 JAN 2015 00:44:11 +0000"], ["SENDER", "NOLAN=YBEATNIKZ.NET@BEATNIKZ.NET"], ["CONTENT-TRANSFER-ENCODING", ["7BIT", {}]]]
MESSAGE-ID: 
RECIPIENT: MGBOX01@GMAIL.COM
SIGNATURE: EB9FE5C673522299A2259052E56487E54F4D2486A0F1582E91D2C17114A6398
TIMESTAMP: 1420591452
TOKEN: E40542A95B5A6989B5E226CC0E9BB2F120478AF8EE594F884C
X-MAILGUN-SID: WYI3NGU3NYISICJTZ2JVEDAXQGDTYWLSLMNVBSISICI0MGRKIL0=
X-MAILGUN-TAG: WEB APP SEPTEMBER NEWSLETTER
X-MAILGUN-TAG: NEWSLETTERS
                                
                            

Ao enviar um e-mail, alguns ESPs permitem que os usuários anexem dados às suas mensagens enviando dados personalizados para os endpoints de API ou SMTP. Esses dados serão representados como um cabeçalho no e-mail e geralmente são formatados em JSON. Eles serão incluídos em qualquer evento de webhook relacionado ao e-mail que os contenha. Mais de um cabeçalho pode ser incluído, e os valores deles serão combinados.

Exemplo:

                                

                                    X-MAILGUN-VARIABLES: {"FIRST_NAME": "JOHN", "LAST_NAME": "SMITH"}
X-MAILGUN-VARIABLES: {"MY_MESSAGE_ID": 123}
                                
                            

Para adicionar esse cabeçalho a uma mensagem:

                                

                                    USING API: PASS THE FOLLOWING PARAMETER, "V:MY-CUSTOM-DATA" => "{"MY_MESSAGE_ID": 123}".
USING SMTP: ADD THE FOLLOWING HEADER TO THE EMAIL, "X-MAILGUN-VARIABLES: {"MY_MESSAGE_ID": 123}".
                                
                            

Ou, se preferir, você pode excluir facilmente um webhook existente:

Às vezes, convém categorizar o tráfego de e-mail de saída com base em alguns critérios, talvez separar e-mails de cadastro de e-mails de recuperação de senha ou comentários da base de usuários. O ESP pode permitir o uso de tags em cada mensagem de saída com um valor personalizado. Esses valores se tornam tags que podem consultar ou agregar estatísticas de entregabilidade. Para adicionar uma tag a uma mensagem de webhook, forneça a ela um ou mais O:TAG.

Amostra de código para inserção de tags:

                                

                                    CURL -S --USER 'API:YOUR_API_KEY' \

HTTPS://API.MAILGUN.NET/V3/YOUR_DOMAIN_NAME/MESSAGES \
-F FROM='SENDER BOB ' \
-F TO='ALICE@EXAMPLE.COM' \
-F SUBJECT='HELLO' \
-F TEXT='TESTING SOME MAILGUN AWESOMNESS!' \
-F O:TAG='SEPTEMBER NEWSLETTER' \
-F O:TAG='NEWSLETTERS'
                                
                            

Para receber os dados de um webhook, os usuários precisam informar ao seu ESP uma URL para a qual as solicitações serão enviadas. Isso significa que eles também devem configurar a URL em seu aplicativo, de modo que ela fique acessível pela web pública e por diferentes endereços IP (daí a necessidade de segurança). Os webhooks do ESP então farão o POST dos dados para a URL como application/x-www-form-urlencoded ou multipart/form-data.

A última etapa é adicionar scripts à URL que capturam os dados fornecidos pelos webhooks e os processam da maneira que a equipe de desenvolvimento achar melhor. É aqui que você pode explorar a criatividade e a granularidade dos atributos que deseja coletar. A melhor maneira de entender isso é usando um exemplo.

Um caso de uso para um webhook pode ser o rastreamento de devoluções de e-mail. Para isso, você terá que capturar um anexo e armazenar o arquivo localmente. Por exemplo, o código a seguir usa uma combinação de microframework para Python, o Flask e a biblioteca Requests HTTP. Este é um aplicativo Flask rápido para capturar um arquivo de um webhook de devolução, manter o nome nativo do arquivo e armazená-lo localmente no seu servidor da web.

                                

                                    FROM FLASK IMPORT FLASK
FROM FLASK IMPORT REQUEST
FROM WERKZEUG IMPORT SECURE_FILENAME
APP = FLASK(__NAME__)

@APP.ROUTE('/WEBHOOK', METHODS=['GET', 'POST'])
DEF TRACKING():
#CHECKS IF THE REQUEST IS A POST
IF REQUEST.METHOD == 'POST':
F = REQUEST.FILES['ATTACHMENT-1']
# OBTAINS THE FILESTORAGE INSTANCE FROM REQUEST
FILENAME = SECURE_FILENAME(F.FILENAME)
F.SAVE('/HOME/DIRECTORY/WEBHOOK/'+ FILENAME)
PRINT FILENAME
RETURN "OK"
IF __NAME__ == '__MAIN__':
APP.RUN(HOST='0.0.0.0', PORT=100, DEBUG=TRUE)
                                
                            

Para ver isso na prática, execute seu aplicativo e cole a URL (por exemplo: http://yourdomainhere.com:100/webhook) no webhook de devolução e clique em “Testar webhook”. Você receberá um arquivo chamado “message.mime” com:

                                

                                    RECEIVED: BY LUNA.MAILGUN.NET WITH SMTP MGRT 8734663311733; FRI, 03 MAY 2013 18:26:27 +0000
CONTENT-TYPE: MULTIPART/ALTERNATIVE; BOUNDARY="EB663D73AE0A4D6C9153CC0AEC8B7520"
MIME-VERSION: 1.0
SUBJECT: TEST BOUNCES WEBHOOK
FROM: BOB 
TO: ALICE 
MESSAGE-ID: 
LIST-UNSUBSCRIBE: 
X-MAILGUN-SID: WYIWNZI5MCISICJHBGLJZUBLEGFTCGXLLMNVBSISICI2IL0=
X-MAILGUN-VARIABLES: {"MY_VAR_1": "MAILGUN VARIABLE #1", "MY-VAR-2": "AWESOME"}
DATE: FRI, 03 MAY 2013 18:26:27 +0000
SENDER: BOB_USER_ID@AWESOME_WORKFLOWS.MAILGUN.ORG
--EB663D73AE0A4D6C9153CC0AEC8B7520
MIME-VERSION: 1.0
CONTENT-TYPE: TEXT/PLAIN; CHARSET="ASCII"
CONTENT-TRANSFER-ENCODING: 7BIT
HI ALICE, DO YOU EXIST ON THIS DOMAIN?
--EB663D73AE0A4D6C9153CC0AEC8B7520
MIME-VERSION: 1.0
CONTENT-TYPE: TEXT/PLAIN; CHARSET="ASCII"
CONTENT-TRANSFER-ENCODING: 7BIT
HI ALICE, DO YOU EXIST ON THIS DOMAIN?
--EB663D73AE0A4D6C9153CC0AEC8B7520--
                                
                            

Essas quatro etapas ajudarão você a configurar um webhook completo, mas, para aproveitar as vantagens, você precisará acioná-lo e aprender sobre os parâmetros de evento.

Como explicado anteriormente, webhooks são acionados por eventos específicos. No contexto de e-mails, esses eventos incluem aberturas, cliques, solicitações de cancelamento de inscrição e outros eventos relacionados à entrega de e-mail. Veja a seguir um detalhamento completo dos eventos do Mailgun que podem servir de gatilho para um webhook:

• Abertura: este evento ocorre sempre que os destinatários abrem uma mensagem. O rastreamento de aberturas é ativado usando os parâmetros O:TRACKING ou O:TRACKING-OPENS ao enviar uma mensagem.
• Clique: este evento rastreia todas as vezes que os destinatários clicam em links em uma mensagem de e-mail. Ative o rastreamento de cliques usando os parâmetros O:TRACKING ou O:TRACKING-CLICKS ao enviar uma mensagem. Assim como nas aberturas, os registros CNAME apropriados devem ser incluídos no DNS do usuário.
• Cancelamento de inscrição: este evento ocorre quando os destinatários clicam no link de “cancelamento de inscrição” em uma mensagem. Você precisará usar o rastreamento de cancelamento de inscrição do Mailgun para receber essas informações.
• Reclamação de spam: não são todos os ISPs que oferecem suporte a notificações de Feedback Loop (“FBL”) para reclamações de spam, mas certifique-se de obter dados de todos os que o fazem.
• Devolução: diz-se que uma mensagem de e-mail sofre “devolução” se for rejeitada pelo servidor SMTP do destinatário. Elas são frequentemente classificadas como devoluções definitivas ou temporárias, da seguinte forma:
  • Falha permanente (“devolução definitiva”): o destinatário não é encontrado, e o servidor de e-mail do destinatário especifica que ele não existe. O aplicativo deve parar de tentar realizar a entrega para destinatários inválidos após uma falha permanente.
  • Falha temporária (“devolução temporária”): o e-mail não é entregue devido a um problema temporário, como uma caixa de entrada cheia. Os aplicativos podem responder programaticamente a falhas temporárias, tentando um determinado número de vezes antes de remover o endereço do destinatário da lista.
• Entregue: uma entrega bem-sucedida ocorre quando o servidor de e-mail do destinatário responde que aceitou a mensagem. Dependendo do evento, os webhooks podem fornecer vários parâmetros para ajudar a identificar e descrever a mensagem em questão. Esses dados podem então ser processados por meio de scripts para fins de análise. Os parâmetros comuns incluem:
  • Evento
  • Destinatário
  • Domínio de envio
  • Cabeçalhos de mensagem
  • Detalhes de identificação do destinatário: país, região, cidade, dispositivo, cliente de e-mail e SO

Dependendo do ESP, outros parâmetros podem incluir variáveis personalizadas, tags, nomes de campanha, autenticação ou IDs de usuário, entre outros. Além disso, alguns eventos oferecem mais detalhes, como a URL que recebeu o clique, o motivo ou a descrição de um evento negativo ou códigos especiais com detalhes específicos do evento.

Uma URL de recebimento deve ser pública. Para manter o conteúdo seguro, os webhooks devem incluir um registro de data e hora de assinatura e um token para criar um hashmap. Um hashmap é apenas uma maneira de armazenar itens com identificadores. O hashmap também usa uma chave de API para confirmar se os dados vêm do ESP da equipe de desenvolvimento. Você deve programar seu aplicativo para verificar esse hashmap e compará-lo com o do ESP, permitindo que o POST seja feito apenas se os dois corresponderem.

Para verificar se o webhook é originário do ESP correspondente, você deve vincular os valores de registro de data e hora e o token, codificar a string resultante com o algoritmo HMAC (usando a chave de API fornecida pelo ESP como chave e modo digest SHA256) e comparar o hexdigest resultante com a assinatura. Além disso, você pode armazenar o valor do token em cache localmente e se recusar a aceitar quaisquer outras solicitações que tenham o mesmo token. Isso impedirá que hackers usem o token para repetir ou desviar ações.

O código de status retornado (por exemplo, 200 OK) informa ao remetente se o webhook foi processado com sucesso. Sempre monitore essas respostas para garantir a resiliência. Outro nível de segurança seria verificar o registro de data e hora para confirmar que a tentativa do POST foi feita dentro de um determinado período de tempo.

Confira a seguir um exemplo de código Python usado para verificar uma assinatura de webhook:

                                

                                    import hashlib 
import hmac 

def verify(api_key, token, timestamp, signature): 
    message = f"{timestamp}{token}" 
    expected_signature = hmac.new( 
        key=api_key.encode(), 
        msg=message.encode(), 
        digestmod=hashlib.sha256 
    ).hexdigest() 
    return signature == expected_signature
                                
                            

Você pode encontrar informações e códigos completos sobre como criar e excluir diferentes tipos de webhooks em nossa documentação, mas incluímos alguns exemplos comuns abaixo. Dê uma olhada!

Você pode usar nossa API para criar um novo webhook:

                                

                                    POST /domains//webhooks
                                
                            

Ou para atualizar um webhook:

                                

                                    PUT /domains//webhooks/
                                
                            

Ou, se preferir, você pode excluir facilmente um webhook existente:

                                

                                    DELETE /domains//webhooks/
                                
                            

Além disso, você pode obter detalhes sobre qualquer URL de webhook para saber mais:

                                

                                    GET /domains//webhooks/
                                
                            

Obviamente, se listássemos todos os exemplos de como você pode usar nossa API para criar e otimizar webhooks, ficaríamos o dia todo nisso. A verdade é que você pode fazer praticamente o que quiser (prometemos que não vamos contar para a sua mãe).

Embora existam vários métodos de acesso aos dados gerados pela entrega de e-mails, como painéis do ESP e chamadas de API, facilite sua vida e implemente alguns webhooks: eles são a maneira mais flexível e eficiente de coletar dados granulares de mensagens de e-mail.

Em vez de extrair dados do seu ESP, opte por receber dados push contínuos sobre e-mails em tempo real. O Mailgun facilita o uso de webhooks. Isso simplifica o trabalho das equipes que contam com essas informações em tempo real para tomar decisões referentes às campanhas de e-mail atuais e futuras em diferentes aplicativos e serviços na web. Muito bom, não é?

E sabe o que mais é legal? Mais informações sobre webhooks. Para ter informações fáceis e passo a passo sobre como usar webhooks no Mailgun, confira nossa documentação sobre webhooks. Para análises detalhadas como esta, assine nossa newsletter. Afinal, os webhooks não são a única coisa que pode fornecer dados granulares a você.

Autor: The Sinch Mailgun team The Sinch Mailgun team shares news, best practices, and strategies to take your products and apps to the next level using email. Subscribe to our newsletter to get all the articles in your inbox!