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

# Configuração

> Como configurar webhooks na plataforma BonifiQ

Este guia explica como criar e configurar uma assinatura de webhook na plataforma BonifiQ através do painel administrativo.

## Acessando a Configuração de Webhooks

1. Acesse o painel administrativo da BonifiQ
2. No menu lateral, navegue até **Configurações** > **Webhooks**
3. Clique no botão **Criar Nova Assinatura**

***

## Campos do Formulário

### Informações Básicas

<AccordionGroup>
  <Accordion title="Nome" icon="tag">
    Digite um nome descritivo para identificar esta assinatura de webhook.

    **Exemplos:**

    * `Integração CRM`
    * `Notificações de Pedidos`
    * `Sincronização ERP`

    <Tip>
      Use nomes que facilitem a identificação do propósito da integração.
    </Tip>
  </Accordion>

  <Accordion title="URL do Endpoint" icon="link">
    Informe a URL completa que receberá as notificações de webhook.

    **Exemplo:** `https://sua-api.com/webhooks/bonifiq`

    <Warning>
      A URL deve:

      * Usar protocolo HTTPS (obrigatório para segurança)
      * Estar acessível publicamente na internet
      * Responder a requisições HTTP POST
    </Warning>
  </Accordion>

  <Accordion title="E-mail do Responsável" icon="envelope">
    Informe o e-mail que será notificado em caso de problemas com a entrega dos webhooks.

    Você receberá alertas quando:

    * Houver falhas consecutivas na entrega
    * A assinatura for desativada automaticamente
  </Accordion>

  <Accordion title="Status (Ativo/Inativo)" icon="toggle-on">
    Defina se a assinatura está ativa ou pausada.

    * **Ativo**: A assinatura receberá notificações normalmente
    * **Inativo**: A assinatura está pausada e não receberá webhooks

    <Note>
      Você pode desativar temporariamente uma assinatura sem precisar excluí-la.
    </Note>
  </Accordion>
</AccordionGroup>

***

### Seleção de Eventos (Tópicos)

Selecione quais eventos você deseja receber. Você pode marcar um ou mais tópicos conforme a necessidade da sua integração.

<Tabs>
  <Tab title="Transações de Pontos">
    | Evento           | Quando é disparado                          |
    | ---------------- | ------------------------------------------- |
    | Ponto adicionado | Quando pontos são creditados para o cliente |
    | Ponto removido   | Quando pontos são debitados do cliente      |
    | Ponto atualizado | Quando um registro de ponto é modificado    |
  </Tab>

  <Tab title="Pedidos">
    | Evento            | Quando é disparado                            |
    | ----------------- | --------------------------------------------- |
    | Pedido inserido   | Quando um novo pedido é registrado no sistema |
    | Pedido atualizado | Quando um pedido existente é modificado       |
  </Tab>

  <Tab title="Ganho de Pontos">
    | Evento                 | Quando é disparado                            |
    | ---------------------- | --------------------------------------------- |
    | Pontos por compras     | Cliente ganhou pontos por realizar uma compra |
    | Pontos por aniversário | Cliente recebeu bônus de aniversário          |
    | Pontos por cadastro    | Cliente ganhou pontos por se cadastrar        |
    | Pontos por review      | Cliente ganhou pontos por fazer um review     |
    | Pontos por indicação   | Cliente ganhou pontos por indicar amigo       |
    | Pontos por quiz        | Cliente respondeu um quiz                     |
    | Objetivo customizado   | Cliente completou um objetivo personalizado   |
  </Tab>

  <Tab title="Redes Sociais">
    | Evento              | Quando é disparado                     |
    | ------------------- | -------------------------------------- |
    | Seguir no Facebook  | Cliente seguiu sua página no Facebook  |
    | Seguir no Instagram | Cliente seguiu sua página no Instagram |
    | Seguir no LinkedIn  | Cliente seguiu sua página no LinkedIn  |
    | Seguir no TikTok    | Cliente seguiu sua página no TikTok    |
  </Tab>

  <Tab title="Resgates e Cupons">
    | Evento                         | Quando é disparado                        |
    | ------------------------------ | ----------------------------------------- |
    | Troca de pontos por recompensa | Cliente resgatou uma recompensa           |
    | Cupom disponível para uso      | Cliente tem cupom disponível              |
    | Recompensa customizada         | Cliente resgatou recompensa personalizada |
  </Tab>

  <Tab title="Notificações">
    | Evento                    | Quando é disparado                          |
    | ------------------------- | ------------------------------------------- |
    | Expiração de pontos       | Pontos do cliente estão próximos de expirar |
    | Pontos disponíveis        | Notificação sobre pontos para usar          |
    | Alteração de pontos       | Saldo de pontos foi modificado              |
    | Subiu de nível            | Cliente foi promovido de tier               |
    | Desceu de nível           | Cliente foi rebaixado de tier               |
    | Código de validação (OTP) | Código foi enviado ao cliente               |
  </Tab>

  <Tab title="Afiliados">
    | Evento             | Quando é disparado                   |
    | ------------------ | ------------------------------------ |
    | Pontos de afiliado | Afiliado ganhou pontos por indicação |
  </Tab>
</Tabs>

***

## Configurações Avançadas

Expanda a seção **Configurações Avançadas** para acessar opções adicionais.

### Cabeçalhos HTTP (Headers)

Adicione cabeçalhos personalizados que serão enviados junto com cada requisição de webhook.

**Uso comum:** Autenticação da requisição

Clique em **Adicionar Header** e preencha:

* **Nome**: Nome do cabeçalho (ex: `X-API-Key`, `Authorization`)
* **Valor**: Valor do cabeçalho (ex: `seu-token-secreto`)

<Tip>
  **Dica de Segurança:** Configure um header secreto (como `X-Bonifiq-Secret`) e valide esse valor no seu sistema para garantir que a requisição realmente veio da BonifiQ.
</Tip>

**Exemplos de headers comuns:**

| Nome               | Valor                   | Uso                  |
| ------------------ | ----------------------- | -------------------- |
| `X-API-Key`        | `minha-chave-secreta`   | Autenticação simples |
| `Authorization`    | `Bearer meu-token`      | Autenticação OAuth   |
| `X-Bonifiq-Secret` | `segredo-compartilhado` | Validação de origem  |

***

### Método HTTP

Por padrão, as requisições são enviadas via **POST**. Se seu sistema requer outro método, selecione:

* **POST** (padrão e recomendado)
* **PUT**
* **PATCH**

***

### Corpo Personalizado

<Note>
  Esta é uma opção avançada. Na maioria dos casos, recomendamos usar o payload padrão.
</Note>

Se seu sistema precisa receber os dados em um formato específico diferente do padrão, você pode ativar o **Corpo Personalizado**.

1. Marque a opção **Usar corpo personalizado**
2. No campo de texto, escreva seu template JSON usando variáveis entre `{{chaves}}`

**Exemplo de template personalizado:**

```json theme={null}
{
  "tipo_evento": "{{Topic}}",
  "cliente": {
    "email": "{{Customer.Email}}",
    "nome": "{{Customer.Name}}"
  },
  "pontos_ganhos": {{EarnedPoints}},
  "data": "{{Timestamp}}"
}
```

**Variáveis disponíveis:**

| Variável                            | Descrição                                                    |
| ----------------------------------- | ------------------------------------------------------------ |
| `{{Customer.Email}}`                | E-mail do cliente                                            |
| `{{Customer.Name}}`                 | Nome do cliente                                              |
| `{{Customer.Id}}`                   | ID do cliente                                                |
| `{{Customer.Phone}}`                | Telefone do cliente                                          |
| `{{Customer.PointsBalance}}`        | Saldo de pontos legado no snapshot do cliente                |
| `{{PointsBalance.PointsBalance}}`   | Saldo consolidado de pontos após o processamento do evento   |
| `{{PointsBalance.CashbackBalance}}` | Saldo consolidado de cashback após o processamento do evento |
| `{{EarnedPoints}}`                  | Pontos ganhos no evento                                      |
| `{{OrderId}}`                       | ID do pedido                                                 |
| `{{OrderTotal}}`                    | Valor do pedido                                              |
| `{{CouponCode}}`                    | Código do cupom                                              |
| `{{Topic}}`                         | Nome do evento                                               |
| `{{Timestamp}}`                     | Data/hora do evento                                          |
| `{{Uuid}}`                          | ID único do webhook                                          |

***

## Salvando a Assinatura

Após preencher todos os campos:

1. Revise as informações
2. Clique em **Salvar**
3. A assinatura será criada e começará a receber eventos imediatamente (se marcada como ativa)

***

## Gerenciando Assinaturas

Na lista de assinaturas, você pode:

<CardGroup cols={3}>
  <Card title="Editar" icon="pen">
    Modifique configurações de uma assinatura existente
  </Card>

  <Card title="Pausar/Ativar" icon="toggle-on">
    Desative temporariamente ou reative uma assinatura
  </Card>

  <Card title="Excluir" icon="trash">
    Remova permanentemente uma assinatura
  </Card>
</CardGroup>

***

## Requisitos do seu Endpoint

Para receber os webhooks corretamente, seu endpoint deve:

<Steps>
  <Step title="Aceitar requisições HTTPS">
    O endpoint deve ter um certificado SSL válido
  </Step>

  <Step title="Responder rapidamente">
    Retorne HTTP 200 (OK) em poucos segundos, idealmente em até 5 segundos
  </Step>

  <Step title="Processar de forma assíncrona">
    Receba o webhook, salve/enfileire e responda. Processe os dados depois.
  </Step>

  <Step title="Implementar idempotência">
    Use o campo `Uuid` para evitar processar o mesmo evento duas vezes
  </Step>
</Steps>

<Warning>
  Se o seu endpoint falhar consecutivamente (5+ vezes), a assinatura será automaticamente desativada e o responsável será notificado por e-mail.
</Warning>