Skip to main content

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.

​
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
Sua URL de webhook deve estar acessível publicamente na internet para receber as notificações.

​
Modelo de Webhook

O HYDRA HUB utiliza o seguinte modelo padrão para webhooks: 
{
  "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:
EventoDescrição
transaction.paidUm pagamento foi confirmado
transaction.processingUma transação está em processamento
transaction.pendingUma transação está pendente
transaction.approvedUma transação foi aprovada
transaction.refusedUma transação foi recusada
transaction.chargedbackUma transação sofreu chargeback
transaction.refundedUma transação foi reembolsada
transaction.cancelledUma 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 ou 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
Para desenvolvimento local, recomendamos o uso de ferramentas como ngrok ou localtunnel para criar um túnel seguro para seu servidor local.