Eventos e Referência da API

Referência completa de todos os tipos de eventos de webhook, schemas de payload e especificações HTTP.

Visão Geral dos Eventos

Tipo de Evento	Categoria	Descrição
`checkout.completed`	Pagamentos	Sessão de checkout concluída com sucesso
`payment.completed`	Pagamentos	Pagamento processado com sucesso (inicial ou recorrente)
`payment.failed`	Pagamentos	Pagamento falhou (cartão recusado, etc.)
`subscription.created`	Assinaturas	Nova assinatura criada
`subscription.renewed`	Assinaturas	Pagamento recorrente processado com sucesso
`subscription.canceled`	Assinaturas	Assinatura cancelada
`subscription.paused`	Assinaturas	Assinatura pausada
`subscription.resumed`	Assinaturas	Assinatura pausada reativada
`subscription.past_due`	Assinaturas	Pagamento em atraso na assinatura
`customer.created`	Clientes	Novo cliente registrado

Campos Comuns do Payload

Todos os eventos compartilham esta estrutura base:

base-payload.json

{
  "id": "evt_uuid-v4",
  "type": "event.type",
  "created_at": "2026-02-16T14:30:00.000Z",
  "data": { ... }
}

Campo	Tipo	Descrição
`id`	string (UUID)	Identificador único do evento. Use para verificações de idempotência.
`type`	string	O tipo do evento (ex.: `payment.completed`)
`created_at`	string (ISO 8601)	Quando o evento foi criado
`data`	object	Dados do payload específicos do evento (veja abaixo)

Campos comuns de dados

A maioria dos eventos relacionados a pagamentos inclui estes campos no objeto data:

Campo	Tipo	Descrição
`data.customer.email`	string	Endereço de e-mail do cliente
`data.customer.name`	string	Nome completo do cliente (se coletado)
`data.customer.stripe_customer_id`	string	ID do cliente no Stripe
`data.amount`	number	Valor bruto cobrado
`data.net_amount`	number	Valor após dedução da taxa da plataforma
`data.platform_fee`	number	Valor da taxa da plataforma
`data.currency`	string	Código ISO de 3 letras da moeda (ex.: `usd`)

checkout.completed

Disparado quando um cliente conclui uma sessão de checkout com sucesso.

checkout.completed

{
  "id": "evt_a1b2c3d4-e5f6-7890-abcd-000000000001",
  "type": "checkout.completed",
  "created_at": "2026-02-16T14:30:00.000Z",
  "data": {
    "customer": {
      "email": "john@example.com",
      "name": "John Doe",
      "stripe_customer_id": "cus_abc123"
    },
    "amount": 49.99,
    "net_amount": 48.49,
    "platform_fee": 1.50,
    "currency": "usd",
    "checkout_session_id": "cs_abc123",
    "subscription_id": "sub_xyz789",
    "mode": "subscription"
  }
}

Campo	Tipo	Descrição
`checkout_session_id`	string	ID da sessão de checkout do Stripe
`subscription_id`	string \| null	ID da assinatura no Stripe (null para pagamento único)
`mode`	string	`"subscription"` ou `"payment"`

payment.completed

Disparado quando um pagamento é processado com sucesso (tanto inicial quanto recorrente).

payment.completed

{
  "id": "evt_a1b2c3d4-e5f6-7890-abcd-000000000002",
  "type": "payment.completed",
  "created_at": "2026-02-16T14:30:00.000Z",
  "data": {
    "customer": {
      "email": "john@example.com",
      "name": "John Doe",
      "stripe_customer_id": "cus_abc123"
    },
    "amount": 49.99,
    "net_amount": 48.49,
    "platform_fee": 1.50,
    "currency": "usd",
    "subscription_id": "sub_xyz789",
    "invoice_id": "in_abc123",
    "mode": "subscription"
  }
}

payment.failed

Disparado quando uma tentativa de pagamento falha (cartão recusado, fundos insuficientes, etc.).

payment.failed

{
  "id": "evt_a1b2c3d4-e5f6-7890-abcd-000000000003",
  "type": "payment.failed",
  "created_at": "2026-02-16T14:30:00.000Z",
  "data": {
    "customer": {
      "email": "john@example.com",
      "name": "John Doe",
      "stripe_customer_id": "cus_abc123"
    },
    "amount": 49.99,
    "currency": "usd",
    "subscription_id": "sub_xyz789",
    "invoice_id": "in_abc123"
  }
}

Eventos de Assinatura

subscription.created

Disparado quando uma nova assinatura é criada.

subscription.created

{
  "id": "evt_a1b2c3d4-e5f6-7890-abcd-000000000004",
  "type": "subscription.created",
  "created_at": "2026-02-16T14:30:00.000Z",
  "data": {
    "customer": {
      "email": "john@example.com",
      "stripe_customer_id": "cus_abc123"
    },
    "subscription_id": "sub_xyz789",
    "status": "active",
    "current_period_start": "2026-02-16T00:00:00.000Z",
    "current_period_end": "2026-03-16T00:00:00.000Z"
  }
}

subscription.renewed

Disparado quando um pagamento recorrente de assinatura é processado com sucesso.

O payload é semelhante ao payment.completed com detalhes adicionais da assinatura.

subscription.canceled

Disparado quando uma assinatura é totalmente cancelada.

subscription.canceled

{
  "id": "evt_a1b2c3d4-e5f6-7890-abcd-000000000005",
  "type": "subscription.canceled",
  "created_at": "2026-02-16T14:30:00.000Z",
  "data": {
    "customer": {
      "email": "john@example.com",
      "stripe_customer_id": "cus_abc123"
    },
    "subscription_id": "sub_xyz789",
    "canceled_at": "2026-02-16T14:30:00.000Z"
  }
}

subscription.paused / subscription.resumed

Disparado quando uma assinatura é pausada ou reativada. O payload inclui subscription_id e detalhes do cliente.

subscription.past_due

Disparado quando um pagamento recorrente falha. Este é um aviso de que a assinatura pode estar em risco. O payload inclui o amount que falhou e o invoice_id.

customer.created

Disparado quando um novo cliente é criado pela primeira vez.

customer.created

{
  "id": "evt_a1b2c3d4-e5f6-7890-abcd-000000000006",
  "type": "customer.created",
  "created_at": "2026-02-16T14:30:00.000Z",
  "data": {
    "customer": {
      "email": "john@example.com",
      "name": "John Doe",
      "stripe_customer_id": "cus_abc123"
    }
  }
}

Especificação HTTP

Cabeçalhos da requisição

Cabeçalho	Valor
`Content-Type`	`application/json`
`X-Stryhub-Signature`	`t=1708100000,v1=hex_signature`
`X-Stryhub-Event`	Tipo do evento (ex.: `payment.completed`)
`X-Stryhub-Delivery`	UUID único de entrega
`User-Agent`	`Stryhub-Webhooks/1.0`

Resposta esperada

Seu endpoint deve retornar um código de status 2xx para confirmar o recebimento. O corpo da resposta é registrado nos logs, mas não é processado.

Código de Status	Significado
`200-299`	Sucesso — marcado como entregue
`300-499`	Falha — a entrega será reenviada
`500+`	Falha — a entrega será reenviada
Timeout (15s)	Falha — a entrega será reenviada

Timeout

As requisições de webhook têm um timeout de 15 segundos. Se seu endpoint não responder dentro de 15 segundos, a entrega é tratada como falha e será reenviada.

Boa prática: Se você precisa de mais de 15 segundos para processar um evento, confirme o recebimento do webhook imediatamente com uma resposta 200 e processe-o de forma assíncrona em um job em segundo plano.

Endereços IP

As requisições de webhook são originadas dos servidores da stryhub. Se você precisa adicionar IPs a uma lista de permissão, entre em contato com o suporte para obter a lista atual de endereços IP de saída.