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

# Webhooks

<Warning>Para utilizar nossas APIs e Webhooks de linhas virtuais, é necessário aderir ao nosso [manual de branding](/api-reference/branding)</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 [Chaves de API](/api-reference/api-keys).

## 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
5. Para maior segurança, sugerimos que seu sistema também [verifique a integridade dos dados recebidos](/api-reference/webhooks/verifying-payloads)

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

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

* **SMS Recebido**: notifica quando um SMS é recebido por um número virtual

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)