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

# Webhooks

> Os webhooks permitem que seu sistema receba notificações automáticas sobre eventos importantes na plataforma HYDRA HUB. Isso elimina a necessidade de consultar a API constantemente para verificar mudanças de status.

## Como Funcionam os Webhooks

Quando um evento ocorre na HYDRA HUB (como uma transação aprovada ou uma entrega concluída), nosso sistema envia uma requisição HTTP POST para uma URL que você definiu, contendo informações detalhadas sobre o evento.

## Configuração de Webhooks

Para configurar webhooks, acesse seu painel na HYDRA HUB:

1. Navegue até **Webhook**
2. Insira a URL de destino para receber as notificações
3. Selecione os eventos que deseja monitorar

<Warning>
  Sua URL de webhook deve estar acessível publicamente na internet para receber as notificações.
</Warning>

## Modelo de Webhook

O HYDRA HUB utiliza o seguinte modelo padrão para webhooks:

```json
{
  "id": "string",
  "type": "transaction",
  "transaction": "url",
  "data": {
    "object": {
      "id": "string",
      "ip": "string | null",
      "fee": {
        "netAmount": "number",
        "fixedAmount": "number",
        "estimatedFee": "number",
        "spreadPercentage": "number"
      },
      "pix": {
        "qrcode": "string"
      },
      "items": [
        {
          "id": "integer",
          "title": "string",
          "saleId": "integer",
          "physical": "boolean",
          "quantity": "integer",
          "createdAt": "date-time",
          "productId": "integer | null",
          "unitPrice": "number",
          "productImg": "integer | null",
          "externalRef": "integer | null",
          "productDesc": "integer | null",
          "productFile": "integer | null",
          "productName": "integer | null",
          "productPage": "integer | null",
          "productType": "integer | null",
          "productBanner": "integer | null"
        }
      ],
      "amount": "number",
      "boleto": {
        "url": "string",
        "barcode": "string",
        "paidAt": "date-time | null"
      },
      "refundedAt": "date-time | null",
      "status": "paid | processing | pending | approved | refused | chargedback | refunded | cancelled | chargeback",
      "customer": {
        "id": "string",
        "name": "string",
        "email": "string",
        "phone": "string",
        "address": {
          "id": "integer",
          "fee": "number",
          "saleId": "integer",
          "street": "string",
          "tracking": "integer | null",
          "steetCity": "string",
          "streetState": "string",
          "streetNumber": "string",
          "streetCountry": "integer | null",
          "streetZipCode": "string",
          "tracking_code": "integer | null",
          "tracking_status": "string",
          "streetComplement": "string",
          "streetNeighborhood": "string"
        },
        "document": {
          "type": "string",
          "number": "string"
        }
      },
      "delivery": {
        "status": "string",
        "createdAt": "date-time",
        "trackingCode": "string | null"
      },
      "metadata": "object | null",
      "secureId": "string",
      "companyId": "string",
      "tenant": "string",
      "traceable": "boolean",
      "paidAmount": "number",
      "externalRef": "string | null",
      "postbackUrl": "string",
      "installments": "integer",
      "paymentMethod": "string",
      "refusedReason": "string | null",
      "splits": [
        {
          "Type": "object"
        }
      ],
      "refunds": [
        {
          "Type": "object"
        }
      ],
      "refundedAmount": "number",
      "createdAt": "date-time"
    }
  }
}
```

## Eventos Disponíveis

O HYDRA HUB oferece os seguintes eventos para webhooks:

| Evento                    | Descrição                           |
| ------------------------- | ----------------------------------- |
| `transaction.paid`        | Um pagamento foi confirmado         |
| `transaction.processing`  | Uma transação está em processamento |
| `transaction.pending`     | Uma transação está pendente         |
| `transaction.approved`    | Uma transação foi aprovada          |
| `transaction.refused`     | Uma transação foi recusada          |
| `transaction.chargedback` | Uma transação sofreu chargeback     |
| `transaction.refunded`    | Uma transação foi reembolsada       |
| `transaction.cancelled`   | Uma transação foi cancelada         |

## Segurança dos Webhooks

Para garantir que os webhooks recebidos são autênticos e provêm da HYDRA HUB, você pode:

### 1. Verificar a origem da requisição

Confirme se a requisição está vindo dos IPs oficiais da HYDRA HUB.

### 2. Responder corretamente

Para confirmar o recebimento de um webhook, seu servidor deve responder com um código de status HTTP 200. Qualquer outro código de resposta será interpretado como falha na entrega, e a HYDRA HUB tentará reenviar a notificação.

## Retentativas

Se seu endpoint retornar um código diferente de 200 ou não responder dentro de 10 segundos, a HYDRA HUB seguirá uma política de retentativas:

* 1ª retentativa: 1 minuto após a falha
* 2ª retentativa: 5 minutos após a falha
* 3ª retentativa: 30 minutos após a falha
* 4ª retentativa: 2 horas após a falha
* 5ª retentativa: 6 horas após a falha

Após cinco tentativas sem sucesso, o webhook será marcado como falho e não será reenviado automaticamente.

## Testando Webhooks

Para facilitar o desenvolvimento e teste de integrações com webhooks, recomendamos:

1. Utilizar ferramentas como [ngrok](https://ngrok.com/) ou [webhook.site](https://webhook.site/) para testar o recebimento de notificações
2. Manter logs detalhados das notificações recebidas para depuração
3. Implementar tratamento adequado para cada tipo de evento

<Tip>
  Para desenvolvimento local, recomendamos o uso de ferramentas como ngrok ou localtunnel para criar um túnel seguro para seu servidor local.
</Tip>