> For the complete documentation index, see [llms.txt](https://docs.giro.tech/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.giro.tech/desenvolvedores/api-gtpayroll/webhooks.md).

# Webhooks

O GTPayroll avisa o seu sistema por **HTTP POST** quando um evento acontece (margem consultada, averbação concluída, pagamento realizado etc.), sem polling.

## Como funciona

* A configuração é por originador: uma ou mais URLs **HTTPS** públicas, um header de autenticação (nome e valor definidos por você) e a assinatura ativa. Crie e altere pela [Configuração via API](https://docs.giro.tech/desenvolvedores/api-gtpayroll/webhooks/configuracao-via-api.md).
* Cada evento é enviado para **todas** as URLs configuradas.
* Falhou, a plataforma retenta com backoff exponencial. Ver [Retry e Garantias](https://docs.giro.tech/desenvolvedores/api-gtpayroll/webhooks/retry-e-garantias.md).
* A assinatura pode ser ativada ou desativada a qualquer momento.

## Formato da requisição

`POST` com `Content-Type: application/json`, o header de autenticação da assinatura e um **envelope** no body:

* **source** — origem do evento (`EMPLOYEE`, `CONTRACT`, `GTBANKER`, `AUTHORIZATION_DOCUMENT`, `DATAPREV_SUSPENSION_WINDOW`, `AUCTION`, `TERMINATED_LOAN_NEW_BOND`)
* **eventType** — tipo do evento (ex.: `MARGIN_QUERY_COMPLETED`, `ENDORSEMENT_ENDORSED`)
* **data** — payload do evento; a estrutura varia conforme `eventType`

```http
POST https://seu-servidor.com/webhook
Content-Type: application/json
Authorization: <seu-token>

{
  "source": "EMPLOYEE",
  "eventType": "MARGIN_QUERY_COMPLETED",
  "data": {
    "cpf": "12345678901",
    "publicId": "Kj8mP2xQ9nR4sT6v",
    "status": "MARGIN_UPDATED",
    "employmentRelationships": [
      {
        "status": "ACTIVE",
        "availableMargin": 1697.76,
        "usableMargin": 1697.76,
        "isEligible": true,
        "alerts": [],
        "legacyLoans": []
      }
    ]
  }
}
```

Payload de cada evento em [Eventos e Payloads](https://docs.giro.tech/desenvolvedores/api-gtpayroll/webhooks/eventos-e-payloads.md).

## Collection Postman

Para testar o seu receptor, importe a collection com um exemplo de payload de **cada** evento — margem, autorização, averbação, pagamento, contrato, leilão e janela Dataprev:

{% file src="/files/bhmU88oYaPQncUW4ZQlI" %}
Exemplos de payload de cada evento de webhook do GTPayroll. Configure `webhook_url` (o seu endpoint), `auth_header_key` e `auth_header_value`, e dispare cada evento para testar o seu receptor.
{% endfile %}
