SMS Webhooks

Webhooks de SMS são um mecanismo que permite ao cliente receber, em tempo real, eventos relacionados com o estado de entrega de SMS 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 SMS transacional permite a configuração de 3 webhooks, que representam 3 estados de entrega do SMS:

• Entregue;
• Pendente;
• Não entregue.

Esta configuração é feita na propriedade smsWebhooks do payload, usado do endpoint para envio de SMS, 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 SMS estará associado a um evento diferente relacionado ao SMS enviado. Exemplo de configuração (dentro do payload de envio de Sms):

...
"smsWebhooks": {
    "delivered": {
        "url":"https://your-endpoint-here.com/delivered",
        "enabled": true
    },
    "not_delivered": {
        "url":"https://your-endpoint-here.com/notdelivered",
        "enabled": true
    },
    "pending": {
        "url":"https://your-endpoint-here.com/pending",
        "enabled": true
    },
    "customPayload": "{\"abc\": "123"}"
}
...

Invocações

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

[
    {
        "Msisdn": <string>,
        "Status": <string>,
        "MessageId": <uuidv4>,
        "OrganizationId": <uuidv4>,
        "ReportDescription": <string>,
        "ReportDateTime": <datetime>,
        "TotalSegments": <int>,
	"CustomPayload": <string>
    }
    ...
]

Para além da configuração granular por endpoint, o webhook indica - na propriedade Status - qual o estado da mesma: DELIVERED, NOT_DELIVERED ou PENDING, sendo por isso possível usar o mesmo endpoint na configuração para os 3 estados, se assim desejar.

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.

Observações

• Os estados DELIVERED e NOT_DELIVERED são estados de entrega finais para o SMS, no entanto. O estado PENDING representa um estado transitório no percurso de entrega do SMS, pelo que poderão ser enviados vários pedidos com este estado, até à chegada de um estado final. O nosso sistema não garante a ordem da entrega, pelo que a lógica de negócio do sistema do cliente deve estar consciente desta regra;

• 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 webhooks com diferentes estados, até um total de 1000 por HTTP request, sendo comum que, para cada SMS enviada, seja espoletado um HTTP request com dois webhooks - um de estado PENDING e outro de estado DELIVERED (estado final);

• 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 perspetiva 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.