> For the complete documentation index, see [llms.txt](https://docs.agnosticdata.ai/agnosticdata.ai-or-documentation/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.agnosticdata.ai/agnosticdata.ai-or-documentation/fundamentals/features/postbacks.md).

# Postbacks

## Conceito

A funcionalidade de **postback** é crucial para garantir o rastreamento eficiente de eventos em campanhas de marketing e integração com terceiros. 

Quando um evento específico, como uma conversão ou ação do usuário, ocorre, os dados relevantes — incluindo informações detalhadas como UTM parameters — são enviados automaticamente para uma URL pré-definida. 

<figure><img src="/files/RbnFL8LVRgvCzPIsn0vo" alt="" width="563"><figcaption></figcaption></figure>

Os postbacks permitem que as equipes de marketing acompanhem com precisão o desempenho de campanhas, otimizem estratégias de aquisição e atribuam corretamente os resultados aos canais e campanhas corretos mesmo com ferramentas de hospedagem ou análise dos eventos diferentes, mas com a precisão da mesma ferramenta coleta.&#x20;

<figure><img src="/files/7aJXuP5AIjbJV4qG4ovF" alt="" width="375"><figcaption></figcaption></figure>

### Como funciona, o básico.&#x20;

A **funcionalidade de postback** permite que o sistema dispare uma requisição HTTP POST para uma URL específica sempre que um evento X ocorrer. Essa requisição inclui dados e parâmetros UTM, facilitando a integração com plataformas de análise e marketing. A implementação dessa funcionalidade garante que os dados de eventos sejam transmitidos de forma automática e em tempo real para a URL alvo, possibilitando o rastreamento preciso e a integração entre diferentes sistemas.

<figure><img src="/files/x6QWhylbVrNNhVusOZTI" alt=""><figcaption><p>Processo de definição para os disparos Postback (útil para integração ou envio de eventos a terceiros)</p></figcaption></figure>

### Entendendo as regras: Postback Rules (url)

Permite enviar um evento de volta (Postback) para um URL de destino baseado em:

1. &#x20;rota
2. evento de página e&#x20;
3. parâmetros de URL.&#x20;

Vamos detalhar o que cada parte dessa configuração representa e como ela poderia ser utilizada em uma implementação prática.

<figure><img src="/files/LHLniAd6ARuqJNfhAF7k" alt=""><figcaption></figcaption></figure>

**Exemplo de regras aplicadas em um payload JSON:**

```javascript
[
  {
    "url_target": "http://localhost:8080/test", // rota alvo para ação
    "utm_case_strategy": "any", // pode ser 'any', 'now', 'before'
    "utm_case_target": {
      "utm_source": "agnostic", // Valores como 'utm_medium' e 'utm_campaign' também podem ser configurados
    },
    "triggedByEvent": "agScriptLoaded", // agScriptLoaded, popstate, load, etc.
    "to_request": {
      "type": "IMAGE", // Pode ser 'IMAGE', 'GET', 'POST', 'PUT', 'DELETE'
      "url": "https://tracking.youragency.com/routeX",
      "add_params": {
        "offer_id": "40",
        "aff_id": "1"
      },
      "pinch": [
        { "from": "utm_case", "item": "utm_source", "name": "utm_source" },
        { "from": "utm_case", "item": "my_name", "name": "customer" },
        { "from": "utm_case", "item": "abc", "name": "paramX" }
      ]
    }
  }
]

```

Então temos:

<figure><img src="/files/rT49bpDf0tV90rAOblTM" alt=""><figcaption></figcaption></figure>

**Descrição dos componentes das Regras**

* **`url_target`**: URL alvo onde o postback deve ser iniciado ou a ação deve ser realizada. É o domínio mais o caminho relativo sem necessadade dos parâmetros de url (querystring).
  * Exemplos:&#x20;
    * <https://www.uol.com.br/esportes> ou [www.uol.com.br/esportes](http://www.uol.com.br/esportes) (para ambos http ou https)
    * <https://meusite.com/minhapagina>
* **`utm_case_strategy`**: Define a estratégia de quando aplicar a regra consideranto as variáveis em [Histórico](/agnosticdata.ai-or-documentation/fundamentals/estrategias-de-atribuicao.md#estrategias) ou exatamente na URL.&#x20;
  * now: aplicado para utilizar apenas os parâmetros de URL quando estão realmente na URL.
  * before: aplicado para utilizar apenas os parêmtros em histórico independentemente da URL. Lembrando todas as variáveis são armazenadas em histórico até o "reset" dos [determinantes](/agnosticdata.ai-or-documentation/fundamentals/estrategias-de-atribuicao.md).&#x20;
  * any: aplicado para ambos os casos, qualquer que seja os parâmetros disponíveis serão utilizados.&#x20;
* **`utm_case_target`**: Especifica os parâmetros UTM que devem ser atendidos para que a regra seja aplicável.
* **`triggedByEvent`**: Especifica o(s) evento(s) que disparam a regra, como o carregamento de um script ou mudanças de visibilidade sendo eles: `DOMContentLoaded, load, popstate, visibilitychange, beforeunload.`
* **`to_request`**: Define como a requisição deve ser feita, incluindo o tipo (imagem, GET, POST, etc.), a URL e quaisquer parâmetros adicionais.
  * **`type`**: Método da requisição.&#x20;
  * **`url`**: Endereço da requisição. É rota para onde deve ser enviado o postback,&#x20;
    * Exemplo: `https://tracking.youragency.com/aff_goal`
  * **`add_params`**: Parâmetros adicionais que devem ser incluídos na requisição.
  * **`pinch`**: Extração de dados de contexto do AgnosticData (ou "pinching") que são adicionados à requisição.
    * **`from`**: De onde os dados devem ser extraídos (e.g., 'utm\_case').
    * **`item`**: Qual item deve ser extraído.
    * **`name`**: Nome sob o qual o item extraído deve ser incluído na requisição. (e pode ser renomeado)