Email Webhooks

Webhooks de Email são um mecanismo que permite ao cliente receber, em tempo real, eventos relacionados com os Emails transacionais enviados através da API Arpoone.

Os URLs configurados pelo cliente serão invocados pelo servidor Arpoone (HTTP POST), enviando informação no formato JSON.

Configuração

O envio de Email transacional permite a configuração de 5 webhooks, que representam 5 eventos relativos ao email:

• Bounced;
• Clicked;
• Opened;
• Spam;
• Unsubscribed.

Esta configuração é feita na propriedade emailWebhooks do payload, usado do endpoint para envio de Email, sendo que o cliente pode escolher quais os eventos para os quais pretende ser notificado (usando a propriedade enabled (bool)).

Cada endpoint configurável pelo cliente no momento do envio do Email estará associado a um evento diferente relacionado ao Email por ele enviado. Exemplo de configuração (dentro do payload de envio de Email):

...
"emailWebhooks": {
    "bounced": {
        "url":"https://your-endpoint-here.com/bounced",
        "enabled": true
    },
    "clicked": {
        "url":"https://your-endpoint-here.com/clicked",
        "enabled": true
    },
    "opened": {
        "url":"https://your-endpoint-here.com/opened",
        "enabled": true
    },
    "spam": {
        "url":"https://your-endpoint-here.com/spam",
        "enabled": true
    },
    "unsubscribed": {
        "url":"https://your-endpoint-here.com/unsub",
        "enabled": true
    }
}
...

Invocações

A estrutura dos webhooks de Email que serão enviados pela Arpoone para cada um dos endpoints indicados pelo cliente é a seguinte:

application/json
[
  {
    "EventType": <string>,
    "Email": <string>,
    "MessageId": <uuidv4> (Guid),
    "Time": <long>,
    "EventDetails": <object>
  },
  ...
]

Os webhooks de Email indicam, na propriedade EventType, qual o tipo de evento ocorrido, sendo possível utilizar o mesmo endpoint na configuração para os 5 eventos, se assim desejar.

A propriedade MessageId é exatamente a mesma devolvida pelo endpoint de Email da API, nos arrays To / CC / BCC, identificando a que destinatário o evento diz respeito.

Importante: O cliente deverá garantir que é retornado código 200 (HTTP OK) em casos de sucesso, caso contrário o webhook segue para uma fila de re-tentativa de envio.

Em cada webhook existe a propriedade EventDetails que é um object e contém informações relacionadas com o evento concreto ocorrido. Os objetos de EventDetails são diferentes consoante o tipo de evento ocorrido devendo ser tomadas a medidas necessárias para o correcto processamento dos mesmos. Seguem as estruturas:

Open

"EventDetails": {
  "CountryCode": <string>,
  "IpAddress": <string>,
  "UserAgent": <string>
}

Click

"EventDetails": {
  "CountryCode": <string>,
  "IpAddress": <string>,
  "UserAgent": <string>,
  "Link": <string>
}

Bounce

"EventDetails": {
  "IsBlocked": <bool>,
  "IsHardBouce": <bool>,
  "BounceType": <string>,
  "BounceDescription": <string>
}

Unsubscribe

"EventDetails": {
  "CountryCode": <string>,
  "IpAddress": <string>,
  "UserAgent": <string>
}

Spam

"EventDetails": {
  "FeedbackLoopSource": <string>
}

Observações

• Deverá ser dada especial atenção ao facto de que no pedido HTTP feito pela Arpoone, o corpo do pedido é um array que pode conter um ou mais eventos de Email, até um total de 1000 por HTTP request;

• Sugerimos a utilização da ferramenta https://webhook.site para validações/testes do funcionamento, utilizando o valor "Your Unique URL" fornecido pela ferramenta como endpoint na configuração dos webhooks;

• Numa prespetiva de optimização de desempenho, o cliente deverá efetuar o processamento dos webhooks de forma assíncrona, por forma a garantir um tempo de resposta curto aos pedidos HTTP da Arpoone.