> ## Documentation Index
> Fetch the complete documentation index at: https://docs.salvy.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Introdução a Webhooks

export const v_1 = "v3"

export const v_0 = "v3"

<Warning>Para utilizar nossas APIs e Webhooks de linhas virtuais, é necessário aderir ao nosso <a href={"/api-reference/" + v_0 + "/branding"}>manual de branding</a></Warning>

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 <a href={"/api-reference/" + v_1 + "/api-keys"}>Chaves de API</a>.

## Como funcionam os webhooks

A Salvy utiliza a plataforma [Svix](https://www.svix.com) 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](https://docs.svix.com/receiving/introduction).

1. Crie uma URL em seu sistema para receber as requisições de webhook
2. Acesse a página de [configurações de Webhooks](https://app.salvy.com.br/settings/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](#entrega-e-novas-tentativas)
5. Para maior segurança, sugerimos que seu sistema também <a href={"/api-reference/" + v_1 + "/webhooks/verifying-payloads"}>verifique a integridade dos dados recebidos</a>

## Formato da requisição

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

```json theme={null}
{
  "type": "event.name",
  "timestamp": "2025-09-03T12:34:56Z",
  "data": {
    // Dados específicos do evento
  }
}
```

| Campo       | Descrição                                                  |
| ----------- | ---------------------------------------------------------- |
| `type`      | Identificador do tipo de evento (ex: `sms.received`)       |
| `timestamp` | Data e hora em que o evento foi gerado, em formato ISO8601 |
| `data`      | Objeto contendo os dados específicos do evento             |

## 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.

<Tip>
  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.
</Tip>

### 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:

| Tentativa | Momento do envio                     | Tempo acumulado total |
| --------- | ------------------------------------ | --------------------- |
| 1ª        | Imediatamente                        | 0                     |
| 2ª        | 5 segundos após a tentativa anterior | 5 segundos            |
| 3ª        | 5 minutos após a tentativa anterior  | \~5 minutos           |
| 4ª        | 30 minutos após a tentativa anterior | \~35 minutos          |
| 5ª        | 2 horas após a tentativa anterior    | \~2h35                |
| 6ª        | 5 horas após a tentativa anterior    | \~7h35                |
| 7ª        | 10 horas após a tentativa anterior   | \~17h35               |
| 8ª        | 10 horas após a tentativa anterior   | \~27h35               |

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.

<Warning>
  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.
</Warning>

### 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](https://app.salvy.com.br/settings/webhooks).

### Como se recuperar de uma falha

<Steps>
  <Step title="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](https://app.salvy.com.br/settings/webhooks).
  </Step>

  <Step title="Reative o endpoint, se ele tiver sido desativado">
    Endpoints desativados precisam ser reativados manualmente na mesma página.
  </Step>

  <Step title="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.
  </Step>
</Steps>

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:

* <a href={"/api-reference/" + v_1 + "/webhooks/sms-received"}>SMS recebido</a> (`sms.received`): quando um SMS é recebido pelo número virtual
* <a href={"/api-reference/" + v_1 + "/webhooks/phone-account-activated"}>Linha ativada</a> (`phone-account.activated`): quando uma linha é ativada
* <a href={"/api-reference/" + v_1 + "/webhooks/phone-account-blocked"}>Linha bloqueada</a> (`phone-account.blocked`): quando uma linha é bloqueada
* <a href={"/api-reference/" + v_1 + "/webhooks/phone-account-unblocked"}>Linha desbloqueada</a> (`phone-account.unblocked`): quando uma linha é desbloqueada
* <a href={"/api-reference/" + v_1 + "/webhooks/phone-account-canceled"}>Linha cancelada</a> (`phone-account.canceled`): quando uma linha é cancelada
* <a href={"/api-reference/" + v_1 + "/webhooks/phone-account-reactivated"}>Linha reativada</a> (`phone-account.reactivated`): quando uma linha é reativada
* <a href={"/api-reference/" + v_1 + "/webhooks/phone-account-esim-ready"}>eSIM pronto para instalação</a> (`phone-account.esim-ready`): quando o código de ativação do eSIM de uma linha fica disponível

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](https://www.standardwebhooks.com/simulate/svix)