Endpoints de webhooks

Um webhook_endpoint é uma URL sua que a Chargefy chama quando os eventos que você assinou acontecem. Cada endpoint tem um secret próprio para verificar a assinatura das entregas e ouve exatamente um fluxo de eventos (events_from): os eventos da própria organização, ou os eventos das organizações conectadas quando você opera uma plataforma. O fluxo é definido na criação e não muda. Para receber os dois fluxos, crie dois endpoints — pode ser a mesma URL, cada um com seu secret. Veja Fan-out para plataformas.

A lista events aceita somente tipos exatos do catálogo. Wildcards como payment.intent.*, charge.* ou * não são suportados. Os eventos organization.* são exclusivos de events_from: "platform" e não podem ser assinados por um endpoint com events_from: "organization".

O secret

O secret segue o formato whsec_<base64 de 32 bytes aleatórios> e aparece somente na resposta do create. Guarde-o nesse momento: GET, list e update nunca retornam o secret. Para trocá-lo, use “Resetar Secret” no dashboard — veja Rotação de secret.

Data Object

{
  "id": "we_U9wziK2k1cxLkxch",
  "object": "webhook_endpoint",
  "created_at": "2026-07-19T12:00:00Z",
  "events": [
    "payment.intent.succeeded",
    "charge.refunded"
  ],
  "events_from": "organization",
  "livemode": true,
  "metadata": {},
  "name": "Servidor principal",
  "updated_at": null,
  "url": "https://meusite.com/webhooks/chargefy"
}

string

Identificador do endpoint. Usa o prefixo we_*.

string

Sempre "webhook_endpoint".

string

Data de criação em ISO 8601.

array

Tipos de evento que o endpoint recebe. Só eventos do catálogo público são aceitos. Os valores são comparados por igualdade; não há expansão de wildcard.

string

Fluxo de eventos que o endpoint ouve. Imutável após a criação.

Valor	Descrição
`organization`	Eventos da própria organização.
`platform`	Eventos das organizações conectadas ativas da sua plataforma, no mesmo ambiente. Não inclui os eventos próprios da organização da plataforma. No payload, `organization` é a organização conectada que originou o evento.

boolean

true em produção; false em ambiente de teste. Definido pelo ambiente da API key usada na criação.

object

Reservado. Endpoints de webhook ainda não aceitam metadata; retorna sempre {}.

string | null

Nome interno para identificar o endpoint no dashboard.

string | null

Data da última atualização em ISO 8601.

string

URL que recebe as entregas via POST. Em produção precisa ser https.

Operações

Para Payment Intents

Cadastre explicitamente:

[
  "payment.intent.created",
  "payment.intent.updated",
  "payment.intent.succeeded",
  "payment.intent.canceled"
]

Criar endpoint

Exemplos para organização e plataforma.

Entrega e assinatura

Headers oficiais, timeout, retries, duplicação, ordem e fan-out.

Fundamentos da API

Objetos de sistema

Webhooks e eventos

SDKs

MCP

Endpoints de webhooks

O secret

Data Object

Operações

Para Payment Intents

Criar endpoint

Entrega e assinatura

​O secret

​Data Object

​Operações

​Para Payment Intents

Criar endpoint

Entrega e assinatura

O secret

Data Object

Operações

Para Payment Intents