Webhook é um recurso usado para integrar o PowerSign com outros sistemas, enviando dados em tempo real sempre que um evento importante ocorre, como assinatura de um documento, criação ou finalização de um envelope. Assim, diferentes sistemas podem trocar informações automaticamente, sem depender de ações manuais.
Hoje, as webhooks do PowerSign podem ser configuradas para enviar informações sempre que os eventos abaixo acontecerem:
Eventos suportados pelo webhook do PowerSign:
- Criação de contrato/envelope (pending)
- Contrato/envelope arquivado (filed)
- Contrato/envelope assinado (signed)
- Contrato/envelope cancelado (cancelled)
O webhook é disparado sempre que há alteração desses status.
Como utilizar
1. Crie um endpoint em seu sistema
Você precisa disponibilizar uma URL (endpoint HTTP) que receberá as notificações dos eventos.
2. Configure a URL no PowerSign
No PowerSign, acesse o menu Configuracoes > Integrações > Webhook e cadastre o endpoint que vai receber as notificações.
Clique em Adicionar para criar um novo webhook , ou voce pode clicar pra ativar um que já esteja criado
Para cada webhook você precisa passar as seguintes informações:
Título do webhook
URL
Token
OBS. Lembrando que na url é necessário enviar http:// e a sua url, o nosso webhook também atende urls com https://
3. Cadastre um token de autenticação
Você pode cadastrar um token para aumentar a segurança. O PowerSign enviará esse token no header da requisição (Authorization: Bearer <token>).
Formato da requisição enviada
Quando um evento ocorre, o PowerSign envia um POST para a URL configurada, com o seguinte conteúdo:
O que cada campo significa?
- companyId: Identificador da sua empresa no PowerSign
- documentCode: Código único do documento relacionado ao evento
- envelopeCode: Código único do envelope relacionado ao evento
- newStatus: Novo status após o evento (exemplo:
pending -( pendente),
filed – (arquivado)
signed – (assinado)
cancelled – (cancelado)) - signatoryName: Nome do assinante envolvido (quando aplicável)
- createdAt: Data e hora do evento (em epoch millis)
- delaySeconds: Tempo de atraso (em segundos) antes do envio (geralmente 5 segundos)
Exemplo prático de automação
- Seu sistema pode receber um Webhook sempre que um documento for assinado, atualizando automaticamente o status do contrato.
- É possível disparar notificações internas, iniciar workflows ou registrar informações em outros sistemas.
Observações importantes
- O endpoint cadastrado deve estar acessível pela internet e aceitar requisições POST com conteúdo em JSON.
- Caso configure um token, valide o header Authorization para maior segurança.
- O Webhook pode ser desativado automaticamente caso o PowerSign receba retornos de erro consecutivos ao tentar notificar seu endpoint.
