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

# Webhooks

> Receba notificações automáticas da 4Selet Pay sempre que algo importante acontecer — como um pagamento aprovado ou uma assinatura cancelada.

Pense nos webhooks como **"mensagens enviadas pela 4Selet Pay para o seu sistema"**, sem que você precise ficar consultando a API o tempo todo.

***

## Por que usar webhooks?

Sem webhooks, sua aplicação teria que **perguntar para a API a cada segundo**:

> "Esse pagamento já foi confirmado?"

Isso é lento e ineficiente.

Com webhooks, a 4Selet Pay avisa você **imediatamente**:

> "O pagamento foi confirmado. Aqui estão os dados."

Assim você pode:

* Atualizar o status de um pedido
* Liberar acesso a um produto ou serviço
* Enviar e-mails e notificações automáticas
* Registrar movimentações financeiras

Tudo isso sem fazer seu cliente esperar.

***

## Como funciona na prática?

1. **Você cria um endpoint no seu sistema**\
   Ex.: `https://meusite.com/webhooks/4seletpay`

2. **Você cadastra esse endpoint no painel da 4Selet Pay ou via API**

3. **Sempre que algo importante acontece**, como um pagamento aprovado:
   * A 4Selet Pay envia um `POST` para a sua URL
   * O `POST` contém o tipo do evento e os dados relacionados
   * Seu sistema processa esse evento e responde `200 OK`

***

## Formato do payload

Todos os webhooks da 4Selet Pay seguem o mesmo envelope:

```json theme={null}
{
  "type": "charge.canceled",
  "id": "hook_a1b2c3d4e5f6",
  "webhook_version": "v1",
  "data": { ... }
}
```

| Campo             | Tipo   | Descrição                                                     |
| ----------------- | ------ | ------------------------------------------------------------- |
| `type`            | string | Identificador do evento em notação `entidade.ação`            |
| `id`              | string | Código único da notificação enviada (`hook_...`)              |
| `webhook_version` | string | Versão do formato do payload — sempre `v1` nesta documentação |
| `data`            | object | Dados específicos do evento (veja cada evento abaixo)         |

<Note>
  O campo `webhook_version` acompanha **todos** os eventos desta documentação com o valor `v1`. Ele identifica o formato do payload, para que o seu endpoint possa conviver com formatos futuros sem ambiguidade. Trate valores desconhecidos de forma tolerante.
</Note>

***

## Eventos suportados

| Evento                     | Quando é disparado                                    |
| -------------------------- | ----------------------------------------------------- |
| `charge.canceled`          | Uma cobrança foi cancelada                            |
| `charge.expired`           | Uma cobrança PIX expirou sem pagamento                |
| `card.created`             | Um cartão foi salvo                                   |
| `card.updated`             | Um cartão foi atualizado                              |
| `card.deleted`             | Um cartão foi removido                                |
| `card.expired`             | Um cartão salvo atingiu o fim da validade             |
| `card.token_pending`       | A tokenização de um cartão foi iniciada               |
| `card.token_created`       | Um cartão foi tokenizado e está pronto para cobranças |
| `card.token_failed`        | Não foi possível tokenizar um cartão                  |
| `order.failed`             | Um pedido falhou no processamento                     |
| `order.unprocessed`        | Um pedido não pôde ser processado pelo gateway        |
| `order.challenged`         | Um pedido requer confirmação adicional (OTP)          |
| `invoice.created`          | Uma nova fatura de assinatura foi gerada              |
| `invoice.failed`           | Uma fatura de assinatura não pôde ser cobrada         |
| `subscription.canceled`    | Uma assinatura foi cancelada                          |
| `subscription.delayed`     | Uma assinatura está com cobrança atrasada             |
| `subscription.regularized` | Uma assinatura atrasada foi regularizada              |
| `tax_invoice.issued`       | A nota fiscal de um pedido foi emitida e autorizada   |

Os payloads detalhados de cada evento estão na seção **Eventos** na barra lateral.

<Note>
  A tabela acima lista os eventos cujos payloads estão documentados nesta versão. A lista completa dos eventos que podem ser assinados — incluindo recebedores, KYC e saques — está em [Endpoints de Webhook → Eventos disponíveis](/pages/webhook-endpoints/reference#eventos-disponíveis).
</Note>

***

## Segurança

Cada webhook cadastrado possui uma URL de destino que você controla. Recomendamos:

<Card title="Boas práticas de segurança" horizontal>
  * Use sempre **HTTPS** no endpoint
  * Valide que a requisição vem realmente da 4Selet Pay (ex: verificar um secret fixo na URL ou no header)
  * Registre cada evento recebido e processe cada um **uma única vez** (idempotência)
  * Responda `200 OK` apenas após concluir o processamento
  * Implemente **retentativas** no seu sistema para eventos que falharem no processamento
</Card>

***

## Criando e gerenciando webhooks

Você pode criar, listar, atualizar e excluir suas configurações de webhook via API. Consulte a seção **Webhooks** na aba **Documentação** para os endpoints completos.

<Tip>
  Cada conta pode ter múltiplos endpoints cadastrados. Todos os endpoints ativos recebem os eventos configurados em paralelo.
</Tip>