Configurar webhooks para atualizações em tempo real no Sign.Plus

Os webhooks permitem-lhe receber atualizações em tempo real sobre o estado dos seus envelopes no Sign.Plus. Este artigo guiá-lo-á pelo processo de configuração e tratamento de webhooks para a sua integração com o Sign.Plus.

Passo 1: Criar um webhook

Para começar a receber atualizações em tempo real, primeiro precisa de criar um webhook no Sign.Plus. Veja como:

1. Decida um URL de destino onde deseja receber as notificações do webhook. Este deve ser um endpoint no seu servidor configurado para tratar pedidos POST recebidos.
2. Escolha o(s) evento(s) que deseja monitorizar. Sign.Plus oferece os seguintes eventos de webhook:
   • envelope_completed

      - Quando um envelope é concluído

   • envelope_expired

      - Quando um envelope expira

   • envelope_declined

      - Quando um envelope é recusado

   • envelope_voided

      - Quando um envelope é anulado

3. Utilize a API do Sign.Plus para criar o webhook. Terá de especificar o seu URL de destino e o(s) evento(s) que deseja monitorizar.

Para informações detalhadas sobre como criar um webhook utilizando a API do Sign.Plus, consulte a documentação do endpoint de criação de um webhook.

Passo 2: Tratar notificações de webhook

Depois de configurar o seu webhook, Sign.Plus enviará pedidos POST para o URL especificado sempre que os eventos monitorizados ocorrerem. Aqui está o que precisa de saber sobre o tratamento destas notificações:

1. Método do pedido: Todas as notificações de webhook são enviadas como HTTP 

   POST

    pedidos.

2. Estrutura do payload: O payload do webhook é um objeto JSON que contém duas secções principais:
   • hook

     : Contém metadados sobre o próprio webhook.

   • data

     : Contém informações sobre o envelope que desencadeou o evento.

3. Exemplos de payload: Aqui estão exemplos de payloads para diferentes eventos:

   // ENVELOPE_DECLINED
{
"hook": {
"id": "6697ccb204bd194fa74c22b4",
"event": "envelope_declined",
"target": "<https://webhook.site/47acfde3-bd83-4fbc-9ff1-ea0dc030e118>"
},
"data": {
"id": "6697ccb204bd194fa74c22b4",
"uid": "4a6e29bfc5344ca6ad7cc8beda456481",
"envelope_id": "6697e681c5e364c7c23710d4",
"file_name": "test"
}
}

// ENVELOPE_COMPLETED
{
"hook": {
"id": "6697ccb204bd194fa74c22b4",
"event": "envelope_completed",
"target": "<https://webhook.site/47acfde3-bd83-4fbc-9ff1-ea0dc030e118>"
},
"data": {
"id": "6697ccb204bd194fa74c22b4",
"uid": "4a6e29bfc5344ca6ad7cc8beda456481",
"envelope_id": "6697e681c5e364c7c23710d4",
"file_name": "test"
}
}

// ENVELOPE_EXPIRED
{
"hook": {
"id": "6697ccb204bd194fa74c22b4",
"event": "envelope_expired",
"target": "<https://webhook.site/47acfde3-bd83-4fbc-9ff1-ea0dc030e118>"
},
"data": {
"id": "6697ccb204bd194fa74c22b4",
"uid": "4a6e29bfc5344ca6ad7cc8beda456481",
"envelope_id": "6697e681c5e364c7c23710d4",
"file_name": "test"
}
}

// ENVELOPE_VOIDED
{
"hook": {
"id": "6697ccb204bd194fa74c22b4",
"event": "envelope_voided",
"target": "<https://webhook.site/47acfde3-bd83-4fbc-9ff1-ea0dc030e118>"
},
"data": {
"id": "6697ccb204bd194fa74c22b4",
"uid": "4a6e29bfc5344ca6ad7cc8beda456481",
"envelope_id": "6697e681c5e364c7c23710d4",
"file_name": "test"
}
}
4. Processar a notificação: Quando o seu servidor recebe uma notificação de webhook:
   • Verifique o payload para garantir que se trata de uma notificação de webhook válida.
   • Extraia as informações relevantes do payload.
   • Execute as ações necessárias com base no tipo de evento (por exemplo, atualizar a sua base de dados, notificar utilizadores, despoletar outros processos).

   • Envie uma resposta 

     200 OK

      para confirmar a receção do webhook.

Os webhooks do Sign.Plus só serão enviados a partir dos seguintes endereços IP autorizados:
34.65.253.117
34.65.146.131

Melhores práticas

1. Segurança: Certifique-se de que o endpoint do webhook é seguro. Considere implementar autenticação para o URL do webhook.
2. Idempotência: Conceba o seu manipulador de webhooks para ser idempotente. Isto significa que deve produzir o mesmo resultado mesmo que o mesmo webhook seja recebido várias vezes.
3. Tratamento de erros: Implemente um tratamento de erros robusto na lógica de processamento dos seus webhooks.

Ao seguir este guia, será capaz de configurar e tratar webhooks de forma eficaz, permitindo que a sua aplicação receba atualizações em tempo real sobre os estados dos envelopes no Sign.Plus.