Configurando webhooks para atualizações em tempo real de Sign.Plus

Webhooks permitem que você receba atualizações em tempo real sobre os status dos seus envelopes no Sign.Plus. Este artigo irá guiá-lo através do processo de configuração e manipulação de webhooks para sua integração Sign.Plus.

Passo 1: Criar um webhook

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

1. Decida o URL de destino onde você quer receber notificações de webhook. Este deve ser um endpoint no seu servidor que está configurado para lidar com solicitações POST recebidas.
2. Escolha o(s) evento(s) que você deseja rastrear. Sign.Plus oferece os seguintes eventos webhook:
   • envelope_complete - Quando um envelope é concluído
   • envelope_expirou - Quando um envelope expirar
   • envelope_declined - Quando um envelope é recusado
   • envelope_anulado - Quando um envelope é anulado
3. Use a API Sign.Plus para criar o webhook. Você precisará especificar sua URL de destino e os eventos que você deseja seguir.

Para obter informações detalhadas sobre como criar um webhook usando a API Sign.Plus, consulte a documentação de endpoint de Criar um webhook.

Etapa 2: Tratar as notficações do webhook

Uma vez que você configurar seu webhook, Sign.Plus enviará requisições POST para sua URL especificada sempre que ocorrerem eventos registrados. Veja o que você precisa saber sobre como lidar com essas notificações:

1. Método de solicitação: Todas as notificações de webhook são enviadas como solicitações HTTP POST.
2. Estrutura de carga: A carga de webhook é um objeto JSON que contém duas seções principais:
   • hook: Contém metadados sobre o webhook em si.
   • dados: Contém informações sobre o envelope que acionou o evento.
3. Payload Examples: Here are examples of payloads for different events:
   // 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. Manipulação da notificação: Quando o servidor receber uma notificação do webhook:
   • Verifique se a carga do payload é uma notificação de webhook válida.
   • Extraia as informações relevantes da carga carregada.
   • Execute todas as ações necessárias com base no tipo de evento (por exemplo, atualizar banco de dados, notificar usuários, acionar outros processos).
   • Envie uma resposta200 OKpara reconhecer o recebimento do webhook.

Melhores práticas

1. Segurança: Certifique-se de que seu webhook endpoint é seguro. Considere a implementação de autenticação para o URL do webhook.
2. Idempotency: Design seu webhook para ser idempotent. Isso significa que deve produzir o mesmo resultado, mesmo que o mesmo webhook seja recebido várias vezes.
3. Tratamento de erro: Implementar robusto manipulação de erro em seu logico de processamento de webhook.

Ao seguir este guia, você poderá configurar e lidar com webhooks de forma eficaz, permitindo que seu aplicativo receba atualizações em tempo real sobre status de envelope no Placa. lus.