Skip to main content
Para utilizar nossas APIs e Webhooks de linhas virtuais, é necessário aderir ao nosso manual de branding
Os webhooks são uma forma de receber notificações em tempo real quando certos eventos ocorrem na plataforma Salvy. Em vez de solicitar constantemente atualizações à API (polling), os webhooks permitem que a Salvy envie informações diretamente para seu sistema assim que um evento acontece. Para autenticar suas requisições à API, crie uma chave na página de Chaves de API.

​
Como funcionam os webhooks

A Salvy utiliza a plataforma Svix para garantir uma entrega segura e confiável de webhooks. A página de configurações de Webhooks está disponível no dashboard da Salvy, em Configurações > Funcionalidades > Webhooks. Para mais detalhes de como a página de configurações funciona, e quais recursos estão disponíveis, consulte a documentação da Svix.
  1. Crie uma URL em seu sistema para receber as requisições de webhook
  2. Acesse a página de configurações de Webhooks, cadastre a sua URL e selecione os eventos desejados.
  3. Quando um evento relevante ocorre (como o recebimento de um SMS), a Salvy envia uma requisição HTTP POST para sua URL
  4. Seu sistema processa os dados recebidos e responde com um código de status HTTP 2xx para confirmar o recebimento. Se a resposta não for 2xx, a Salvy tenta reenviar o evento, veja Entrega e novas tentativas
  5. Para maior segurança, sugerimos que seu sistema também verifique a integridade dos dados recebidos

​
Formato da requisição

Todas as requisições de webhook seguem o mesmo formato padrão:

​
Entrega e novas tentativas

Seu endpoint deve responder com um código de status HTTP 2xx em até 15 segundos. Qualquer outra resposta (4xx, 5xx, timeout ou erro de conexão) é tratada como falha, e o evento entra na fila de novas tentativas.
Responda primeiro, processe depois. Se o seu sistema executar todo o processamento antes de responder, uma tarefa demorada pode estourar o tempo limite e fazer com que a Salvy reenvie um evento que você já processou.

​
Cronograma de tentativas

Cada evento é tentado até 8 vezes, ao longo de pouco mais de 27 horas. Cada intervalo começa após a falha da tentativa anterior; a última coluna mostra o tempo total decorrido desde o envio original: Como um mesmo evento pode ser entregue mais de uma vez (por exemplo, quando a sua resposta demora e a conexão cai antes de chegar até nós), trate o recebimento de forma idempotente. O header svix-id é único e estável por evento: use-o para identificar e descartar entregas repetidas.

​
Quando as tentativas se esgotam

Se as 8 tentativas falharem, o evento é marcado como falho e não é mais reenviado automaticamente. Nesse momento, a Salvy avisa os administradores da empresa por e-mail (“Não foi possível entregar um evento”), identificando o endpoint afetado.
Esse aviso se refere a um único evento. Enquanto o endpoint estiver indisponível, outros eventos também vão falhar. Para não inundar a sua caixa de entrada, agrupamos os avisos: você recebe no máximo um e-mail por endpoint a cada 6 horas.

​
Desativação automática do endpoint

Se todas as entregas para um endpoint falharem por cinco dias consecutivos, ele é desativado automaticamente e para de receber eventos. Os administradores recebem um e-mail de aviso (“Desativamos um endpoint da sua integração”). Um endpoint desativado não volta a funcionar sozinho. Depois de corrigir o problema, é preciso reativá-lo manualmente na página de configurações de Webhooks.

​
Como se recuperar de uma falha

1

Verifique o endpoint

Confirme que a URL está acessível publicamente e respondendo 2xx. O histórico de tentativas, com o status HTTP e o corpo de cada resposta, fica na página de configurações de Webhooks.
2

Reative o endpoint, se ele tiver sido desativado

Endpoints desativados precisam ser reativados manualmente na mesma página.
3

Reenvie os eventos que ficaram para trás

Use Recover Failed para reenviar os eventos que falharam a partir de uma data, ou Replay Missing para reenviar os eventos que nunca chegaram a ser tentados enquanto o endpoint esteve desativado. Eventos individuais também podem ser reenviados pelo histórico.
Eventos novos voltam a ser entregues normalmente assim que o endpoint estiver saudável e ativo.

​
Segurança

Para garantir a autenticidade das requisições de webhook, recomendamos:
  1. Utilizar HTTPS para sua URL de webhook
  2. Validar a origem da requisição verificando os cabeçalhos HTTP
  3. Implementar um mecanismo de retry e timeout adequado para lidar com falhas temporárias

​
Eventos disponíveis

Atualmente, a Salvy oferece os seguintes eventos via webhook: Para mais detalhes sobre cada evento, consulte a documentação específica.

​
Testes

Para realizar testes na sua integração de Webhooks, recomendamos o uso da seguinte ferramenta: Standard Webhooks - Simulate Webhooks