# Webhook

## 🌐 Webhooks – Tictools

## Índice

* [O que são Webhooks](#o-que-sao-webhooks)
* [Visão Geral do Menu Webhook](#visao-geral-do-menu-webhook)
* [Pastas](#pastas)
* [Documentação Oficial](#documentacao-oficial)
* [Lista de Webhooks](#lista-de-webhooks)
* [Ações Disponíveis](#acoes-disponiveis)
* [Como Criar um Webhook](#como-criar-um-webhook)
  * [Token](#token)
  * [Itens a serem enviados](#itens-a-serem-enviados)
  * [Produtos](#produtos)
  * [URL](#url)
  * [Versão](#versao)
  * [Formato de Envio](#formato-de-envio)
  * [Seleção de Eventos](#selecione-os-eventos)
* [Validação Automática da URL](#validacao-automatica-da-url)
* [Observações Importantes](#observacoes-importantes)

***

### 🔔 O que são Webhooks

Webhooks são mecanismos que enviam **notificações em tempo real** para outros sistemas quando um evento ocorre na plataforma.

Eles permitem:

* Integrar automações externas ( sistemas de automatização de conversas, áreas de membros externas, entre outros)
* Sincronizar dados imediatamente
* Acompanhar eventos de vendas, assinaturas, afiliações e pagamentos

***

### Como acessar a funcionalidade de webhoooks

Siga o passo a passo abaixo:

{% stepper %}
{% step %} <sub>Abra o menu lateral esquerdo da plataforma, clique na opção Tictools</sub>

<div data-with-frame="true"><figure><img src="https://3610983464-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FnWIfc9hpnMPQKmkeC8kA%2Fuploads%2FWEb8VUxjnJuECPwEVpUz%2Fimage.png?alt=media&#x26;token=83bb6194-6767-49c7-8e15-ccc7f274192b" alt=""><figcaption></figcaption></figure></div>
{% endstep %}

{% step %} <sub>Dentro de Tictools, clique no card</sub> <sub></sub><sub>**Webhooks**</sub>

<div data-with-frame="true"><figure><img src="https://3610983464-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FnWIfc9hpnMPQKmkeC8kA%2Fuploads%2FARUZ11yJSG1axxfIF2cZ%2Fimage.png?alt=media&#x26;token=a952b105-bc32-4c84-beca-f46ded67b60e" alt=""><figcaption></figcaption></figure></div>
{% endstep %}
{% endstepper %}

### 🧭 Visão Geral do Menu Webhook

O menu **Tictools → Webhooks** permite que você:

| Recurso             | Descrição                                   |
| ------------------- | ------------------------------------------- |
| Criar Webhooks      | Configurar URLs e eventos para notificações |
| Organizar em Pastas | Agrupar webhooks por categoria              |
| Testar Webhooks     | Enviar um evento de teste                   |
| Acompanhar Envios   | Ver histórico de disparos                   |
| Editar / Excluir    | Gerenciar webhooks existentes               |

***

### 🗂 Pastas

O usuário pode criar pastas para organizar webhooks.

| Função             | Descrição                                               |
| ------------------ | ------------------------------------------------------- |
| **Nova Pasta**     | Cria uma nova pasta para agrupar webhooks               |
| Nome personalizado | Pasta pode receber qualquer nome                        |
| Organização        | Permite separar webhooks por sistema, produto ou equipe |

***

Para criar uma para e organizar os webhooks por projetos ou produtos, siga o passo a passo:

{% stepper %}
{% step %} <sub>Ainda dentro do menu tictools/webhooks, clique no botão</sub> <sub></sub><sub>**"+nova pasta"**</sub>

<div data-with-frame="true"><figure><img src="https://3610983464-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FnWIfc9hpnMPQKmkeC8kA%2Fuploads%2FBXEuvP2UhqQwGRLSv3kS%2Fimage.png?alt=media&#x26;token=849e2ce5-e396-4db0-bbd8-e5689df0243f" alt=""><figcaption></figcaption></figure></div>
{% endstep %}

{% step %}
Depois insira o nome do projeto que desejar

<div data-with-frame="true"><figure><img src="https://3610983464-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FnWIfc9hpnMPQKmkeC8kA%2Fuploads%2FZPvmRhNdZxRX7TjoZKkr%2Fimage.png?alt=media&#x26;token=1b368cc8-f41d-4d0f-9ffe-16afdc97a419" alt=""><figcaption></figcaption></figure></div>
{% endstep %}

{% step %}
Após digitar o nome do projeto, clique em **"salvar"**

{% endstep %}

{% step %}
Após salvar, você visualizará uma mensagem sinalizado que a pasta foi criada com sucesso.\
&#x20;As pastas aparecerão na lateral esquerda, você pode acessar as pasta para visualizar as integrações ou até mesmo adicionar uma nova.

<div data-with-frame="true"><figure><img src="https://3610983464-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FnWIfc9hpnMPQKmkeC8kA%2Fuploads%2FUGnTfV24mQfsBx9clduy%2Fimage.png?alt=media&#x26;token=13195beb-6bc7-4480-80f3-0885c0b90ce8" alt=""><figcaption></figcaption></figure></div>
{% endstep %}
{% endstepper %}

### 📚 Documentação Oficial

O menu inclui um link direto para a documentação técnica completa dos Webhooks.

<div data-with-frame="true"><figure><img src="https://3610983464-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FnWIfc9hpnMPQKmkeC8kA%2Fuploads%2F0C0Y2ixg4UGU021uO83S%2Fimage.png?alt=media&#x26;token=686262b1-144f-4cfa-a18c-661a2afd8cd8" alt=""><figcaption></figcaption></figure></div>

{% embed url="<https://webhook.ticto.dev/docs/intro>" %}

{% hint style="warning" %}
**Use a documentação para integrar corretamente com sistemas externos.**
{% endhint %}

***

## 📋 Lista de Webhooks

A tabela de webhooks exibe:

| Coluna      | Descrição                                    |
| ----------- | -------------------------------------------- |
| **URL**     | Endereço para onde os eventos serão enviados |
| **Pasta**   | Categoria onde o webhook está organizado     |
| **Produto** | Produto(s) relacionado(s) ao webhook         |
| **Versão**  | Versão 1.0 (legado) ou 2.0 (recomendada)     |
| **Eventos** | Eventos selecionados para envio              |

<div data-with-frame="true"><figure><img src="https://3610983464-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FnWIfc9hpnMPQKmkeC8kA%2Fuploads%2FakD0LzXO0XBWyMUq5Gij%2Fimage.png?alt=media&#x26;token=d2d30396-f728-4c7d-8a39-4579293dac13" alt=""><figcaption></figcaption></figure></div>

***

## 🛠 Ações Disponíveis

Cada webhook possui um menu com:

| Ação                       | O que faz                                  |
| -------------------------- | ------------------------------------------ |
| **Editar**                 | Modificar URL, eventos, versão ou pasta    |
| **Enviar evento de teste** | Envia um payload para validar a integração |
| **Visualizar envios**      | Histórico de disparos (sucessos e falhas)  |
| **Excluir**                | Remove o webhook permanentemente           |

<div data-with-frame="true"><figure><img src="https://3610983464-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FnWIfc9hpnMPQKmkeC8kA%2Fuploads%2FzYQWHpMQ1yXkmkv1Lr1s%2Fimage.png?alt=media&#x26;token=234980e6-3850-4a1a-9762-08c3d1f9233b" alt=""><figcaption></figcaption></figure></div>

***

## ➕ Como Criar um Webhook

A criação envolve alguns passos importantes, veja a seguir:

***

{% stepper %}
{% step %}
Através do menu lateral direito tictools/webhooks, clique sobre o ícone de olho, referente a pasta em que deseja criar o webhook.

<div data-with-frame="true"><figure><img src="https://3610983464-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FnWIfc9hpnMPQKmkeC8kA%2Fuploads%2FgHFhBak28pcHeRUJMl02%2Fimage.png?alt=media&#x26;token=243eb117-a7ba-4bc6-88eb-dcb81085e349" alt=""><figcaption></figcaption></figure></div>
{% endstep %}

{% step %}
Depois clique em no botão **"+adicionar"**

<div data-with-frame="true"><figure><img src="https://3610983464-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FnWIfc9hpnMPQKmkeC8kA%2Fuploads%2F7bkyUlyzRQrjIvK2wkcG%2Fimage.png?alt=media&#x26;token=be5e27f4-980b-4fa5-bb23-3f0c3b0a2918" alt=""><figcaption></figcaption></figure></div>
{% endstep %}

{% step %}

### 🔑 Token

Utilize este token para garantir que os postbacks foram enviados pela Ticto. Não repassa ou compartilhe esta informação.

<div data-with-frame="true"><figure><img src="https://3610983464-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FnWIfc9hpnMPQKmkeC8kA%2Fuploads%2Ft3bYqvtDT17FXtyCZSD5%2Fimage.png?alt=media&#x26;token=7978e221-abd3-4b3b-9fc6-8e238c87265d" alt=""><figcaption></figcaption></figure></div>
{% endstep %}

{% step %}

### 🧱 Itens a serem enviados

Esta seleção determina se os itens de order bump/combo, devem ser enviados junto ao payload do produto principal ou separados.

Caso opte pela opção **Enviar Order Bump | Combo separadamente,** você receberá payloads individuais para cada item.

| Opção                                                      | Descrição                     | Quando usar                                        |
| ---------------------------------------------------------- | ----------------------------- | -------------------------------------------------- |
| **Enviar Order Bump / Combo junto com a oferta principal** | Envia tudo em um único evento | Para integrações que preferem dados unificados     |
| **Enviar Order Bump / Combo separadamente**                | Envia eventos distintos       | Para sistemas que tratam cada item individualmente |

<div data-with-frame="true"><figure><img src="https://3610983464-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FnWIfc9hpnMPQKmkeC8kA%2Fuploads%2F6IctTflsyto70vLWJHzc%2Fimage.png?alt=media&#x26;token=5db172a1-ae31-482f-aff7-7bc9000d2a20" alt=""><figcaption></figcaption></figure></div>
{% endstep %}

{% step %}

### 📦 Produtos

Selecione os produtos que farão parte desta integração e usaram esta url e configurações para envio dos eventos.

<div data-with-frame="true"><figure><img src="https://3610983464-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FnWIfc9hpnMPQKmkeC8kA%2Fuploads%2FTz7fotyi3aeUQY9Vpb0W%2Fimage.png?alt=media&#x26;token=e717bf66-7401-4fb6-81ac-b7240d19717c" alt=""><figcaption></figcaption></figure></div>
{% endstep %}

{% step %}

### 🌍 URL

Insira a url que receberá os eventos&#x20;

<div data-with-frame="true"><figure><img src="https://3610983464-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FnWIfc9hpnMPQKmkeC8kA%2Fuploads%2FyEo9cDsCJNb5qkeWCsCA%2Fimage.png?alt=media&#x26;token=53299bff-f269-4c8c-8e4f-0f80cc8f715e" alt=""><figcaption></figcaption></figure></div>
{% endstep %}

{% step %}

### 🔢 Versão

Defina a versão em que os eventos serão enviados, existem sistemas que só aceitam a versão 1, no entanto recomendamos a utilização da versão 2.

| Versão  | Descrição                    | Recomendação                     |
| ------- | ---------------------------- | -------------------------------- |
| **1.0** | Versão antiga do webhook     | Somente para integrações legadas |
| **2.0** | Versão atual e mais completa | ✔️ Recomendada                   |

<div data-with-frame="true"><figure><img src="https://3610983464-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FnWIfc9hpnMPQKmkeC8kA%2Fuploads%2F7NLVG9gavoegFO1465Cj%2Fimage.png?alt=media&#x26;token=7fd91432-e218-4aaf-9494-28f342c146c7" alt=""><figcaption></figcaption></figure></div>
{% endstep %}

{% step %}

### 📤 Formato de Envio

Este formato define como a resposta chegará na sua url, o modelos mais utilizado é JSON.

| Formato            | Descrição                         | Observação                               |
| ------------------ | --------------------------------- | ---------------------------------------- |
| **JSON**           | Padrão mais moderno e estruturado | ✔️ Recomendado                           |
| **URL Codificado** | Envia dados como querystring      | Necessário para fornecedores como Notazz |

***

<div data-with-frame="true"><figure><img src="https://3610983464-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FnWIfc9hpnMPQKmkeC8kA%2Fuploads%2FuoDEMNWzR126c5BYvxxx%2Fimage.png?alt=media&#x26;token=6e290b72-b71b-4cf0-ad39-0253776c1eda" alt=""><figcaption></figcaption></figure></div>

{% hint style="warning" %}
Alguns fornecedores (como Notazz) precisam de um formato de envio diferente \
Para estes casos, você pode escolher o mais adequado.
{% endhint %}
{% endstep %}

{% step %}

### 📤 Selecione os eventos

Os eventos são os gatilhos responsáveis por enviar as informações para url configurada.\
Assim que um dos eventos selecionados acontecerem será enviado uma resposta com os dados da venda, assinatura, abandono de carrinho etc.\
\
A seguir, a tabela organizada por categorias:

***

### 🛒 **Eventos de Compra**

| Evento                       | Descrição                               | Uso                           |
| ---------------------------- | --------------------------------------- | ----------------------------- |
| **1. Abandono de Carrinho**  | Cliente inicia compra, mas não finaliza | Recuperação de vendas         |
| **2. Boleto Impresso**       | Cliente visualiza/emite boleto          | Lembretes antes do vencimento |
| **4. Pix Gerado**            | Pix criado                              | Acompanhar intenção de compra |
| **18. Pix Expirado**         | Pix expirou sem pagamento               | Oferta de novo link           |
| **15. Venda Realizada**      | Pagamento aprovado                      | Ativar acessos, processamento |
| **19. Venda Recusada**       | Pagamento falhou                        | Solicitar novo método         |
| **20. Aguardando Pagamento** | Venda criada, aguardando compensação    | Fluxos de espera              |
| **16. Boleto Atrasado**      | Boleto venceu sem pagamento             | Recuperação de vendas         |
| **17. Encerrado**            | Operação do boleto finalizada           | Encerramento de fluxo         |

***

### 💳 **Eventos de Assinatura**

| Evento                              | Descrição                         | Uso                             |
| ----------------------------------- | --------------------------------- | ------------------------------- |
| **7. Encerrada**                    | Assinatura finalizada             | Comunicação de encerramento     |
| **8. Extendida**                    | Cliente prolonga assinatura       | Manter serviço ativo            |
| **9. Atrasada**                     | Pagamento não compensado          | Solicitar atualização           |
| **10. Período de Testes Encerrado** | Teste finalizado                  | Notificar conversão/cobrança    |
| **11. Período de Testes Iniciado**  | Teste começou                     | Onboarding                      |
| **12. Cancelada**                   | Assinatura encerrada pelo cliente | Retenção/cancelamento de acesso |
| **13. Cartão Atualizado**           | Cliente alterou cartão            | Evitar falhas futuras           |
| **14. Retomada**                    | Assinatura reativada              | Reativar acessos                |

***

### 🤝 **Eventos de Afiliação**

| Evento                       | Descrição                   | Uso                             |
| ---------------------------- | --------------------------- | ------------------------------- |
| **21. Afiliação Criada**     | Nova solicitação registrada | Analisar novo afiliado          |
| **22. Afiliação Solicitada** | Produtor deve aprovar       | Processo de aprovação           |
| **23. Afiliação Aprovada**   | Afiliação aceita            | Afiliado liberado para promover |

***

### 🧾 **Eventos Especiais**

| Evento                | Descrição                   |
| --------------------- | --------------------------- |
| **3. Chargeback**     | Contestação do pagamento    |
| **5. Reembolso**      | Cliente recebeu reembolso   |
| **6. Tempo de Teste** | Teste de produto finalizado |

<div data-with-frame="true"><figure><img src="https://3610983464-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FnWIfc9hpnMPQKmkeC8kA%2Fuploads%2FSjphECyWfaZHFjsd0xC9%2Fimage.png?alt=media&#x26;token=302036de-c817-4a3b-85c2-a0d80b1ab7f4" alt=""><figcaption></figcaption></figure></div>
{% endstep %}

{% step %}

## 🔍 Validação Automática da URL

Ao cadastrar uma URL, a Ticto envia um **teste automático** antes de permitir salvar.

#### ✔️ Caso o teste seja bem-sucedido:

* Modal informa sucesso
* Usuário pode salvar normalmente

#### ❌ Caso falhe:

* Mensagem explica o erro
* Usuário deve ajustar a URL antes de continuar

> 💡 Essa validação evita erros de configuração e falhas de integração.

* **Criamos uma situação simples para que vejam na prática essa validação.**\
  \
  Para o exemplo abaixo criamos uma url de teste através do site : <https://webhook.site/#!/view/b6126fc7-c779-4802-81e6-e73b4a7ca512><br>

<div data-with-frame="true"><figure><img src="https://3610983464-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FnWIfc9hpnMPQKmkeC8kA%2Fuploads%2Fy5LEbYtj3XuU9oJc2iB8%2Fimage.png?alt=media&#x26;token=17e7f411-879a-4b08-afc0-beedbe2988bb" alt=""><figcaption></figcaption></figure></div>

* **Configuramos os eventos:**

<div data-with-frame="true"><figure><img src="https://3610983464-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FnWIfc9hpnMPQKmkeC8kA%2Fuploads%2FEbT97DGLFFZsjIpF68YX%2Fimage.png?alt=media&#x26;token=335872ba-fcc9-441a-abb4-405bf3732ec3" alt=""><figcaption></figcaption></figure></div>

* Confirme se está tudo ok com a configuração e clique em **Salvar.**

<div data-with-frame="true"><figure><img src="https://3610983464-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FnWIfc9hpnMPQKmkeC8kA%2Fuploads%2F0j55JNCDRvJfyolJIeVL%2Fimage.png?alt=media&#x26;token=2c5c8932-ad1e-42c5-a59d-4a7a6f0f0259" alt=""><figcaption></figcaption></figure></div>

<br>

* &#x20;Reposta do disparo do evento:

<div data-with-frame="true"><figure><img src="https://3610983464-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FnWIfc9hpnMPQKmkeC8kA%2Fuploads%2FdilaKNoyYbT1hxftcrSN%2Fimage.png?alt=media&#x26;token=6c1af3b2-95e9-4bf8-a148-fe1a13ccf655" alt=""><figcaption></figcaption></figure></div>
{% endstep %}
{% endstepper %}

## 📌 Observações Importantes

* O histórico de envios mostra falhas e sucessos.
* Eventos como **Carrinho Abandonado** só disparam quando e-mail ou telefone foram preenchidos.
* Versão 2.0 oferece payloads mais completos e padronizados.
* É possível ver os detalhes e resposta do servidor através do Detalhes do evento.
* É possivel reenviar um evento através do relatório de minhas vendas.