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

# Webhook de plataforma

> POST /api/integrations/{plataforma} — endpoint para webhook automático dos 90+ gateways integrados.

Endpoint que a xTracky expõe pra cada plataforma de pagamento integrada. Você **não chama diretamente** — quem chama é o gateway, com o payload dele. A xTracky normaliza automaticamente pra o formato canônico interno.

<Card icon="webhook">
  **POST** `https://api.xtracky.com/api/integrations/{plataforma}`
</Card>

## Como usar

<Steps>
  <Step title="Descubra o slug">
    Ver [lista completa de plataformas](/plataformas/lista).
  </Step>

  <Step title="Configure o webhook no painel do gateway">
    Cole a URL `https://api.xtracky.com/api/integrations/{slug}`.
  </Step>

  <Step title="Pronto">
    A xTracky recebe, normaliza e dispara conversão pras redes.
  </Step>
</Steps>

Ver o [passo a passo detalhado](/plataformas/configurar-webhook).

## Payload

O payload é **o formato nativo do gateway**. A xTracky mantém um transformer por plataforma que traduz cada campo (currency, status, amount, UTM, lead) pro formato canônico interno.

Ou seja: você não precisa se preocupar com o formato. Se a plataforma está na lista, a xTracky entende.

## Exemplos por gateway

<Tabs>
  <Tab title="Vega">
    ```
    POST https://api.xtracky.com/api/integrations/vega
    ```

    O gateway Vega envia payload com `transaction_id`, `status`, `amount_cents`, `client_utm_source`. Traduzido automaticamente.
  </Tab>

  <Tab title="Cakto">
    ```
    POST https://api.xtracky.com/api/integrations/cakto
    ```

    Cakto envia `order.id`, `payment.status`, `total.amount`, `metadata.utm_source`. Traduzido automaticamente.
  </Tab>

  <Tab title="Shopify">
    ```
    POST https://api.xtracky.com/api/integrations/shopify
    ```

    Shopify envia o objeto `order` completo. A xTracky lê o `note_attributes.xtracky_utm_source` que o [script do Shopify](/scripts/shopify) injetou no pedido.
  </Tab>

  <Tab title="Tribopay">
    ```
    POST https://api.xtracky.com/api/integrations/tribopay
    ```

    Tribopay envia via HMAC-signed webhook. A xTracky valida a assinatura automaticamente.
  </Tab>
</Tabs>

## Resposta

Todos os webhooks respondem sempre `200 OK` (mesmo em caso de dedup) pra evitar que o gateway retente desnecessariamente. Erros de payload são logados no painel em **Dashboard → Webhooks → Falhas**.

```json theme={null}
{
  "success": true,
  "received": true
}
```

<Warning>
  Se o gateway está enviando webhook mas nada aparece no painel, cheque em **Dashboard → Webhooks → Falhas**. Provavelmente há um erro de normalização (campo esperado ausente, status desconhecido, etc.). Ver [Configurar webhook](/plataformas/configurar-webhook) para debug.
</Warning>

## Adicionando uma nova plataforma

Se você é o **dono ou parceiro** da plataforma e quer se integrar oficialmente à xTracky:

<Steps>
  <Step title="Envie a documentação">
    Mande pro [suporte@xtracky.com](mailto:suporte@xtracky.com):

    * Doc de webhook (formato do payload, headers, assinatura HMAC)
    * Exemplo real de payload pra cada tipo de evento
    * Como o cliente configura o webhook no seu painel
  </Step>

  <Step title="Aguarde o transformer">
    Nosso time cria o transformer DB-driven em 3-5 dias úteis. Você recebe o slug (`/api/integrations/{seu-nome}`).
  </Step>

  <Step title="Divulgue">
    A partir daí, seus clientes podem apontar webhook pra xTracky sem código.
  </Step>
</Steps>