Criar um endpoint de webhook

curl -X POST "https://api.chargefy.io/v1/webhook-endpoints" \
  -H "Authorization: Bearer {{API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
    "events": ["payment.intent.succeeded", "charge.refunded"],
    "url": "https://meusite.com/webhooks/chargefy"
  }'

curl -X POST "https://api.chargefy.io/v1/webhook-endpoints" \
  -H "Authorization: Bearer {{API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
    "events": ["payment.intent.succeeded", "organization.created"],
    "events_from": "platform",
    "name": "Vendas das organizações conectadas",
    "url": "https://meusite.com/webhooks/chargefy"
  }'

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

{
  "error": {
    "code": "invalid_request",
    "message": "Unknown event type: payment.succeeded",
    "param": "events",
    "type": "invalid_request_error"
  }
}

{
  "error": {
    "code": "authentication_failed",
    "message": "Unauthorized — invalid api key",
    "type": "authentication_error"
  }
}

Cria um webhook_endpoint. A resposta é a única vez que o secret aparece — guarde-o para verificar as assinaturas das entregas. Obrigatórios: url e events. Todo o resto tem default. Este endpoint aceita Idempotency-Key.

Autenticação

Endpoints de webhook são configuração da própria conta: use a API key da organização com escopo write. A API key de plataforma não gerencia endpoints e o header Organization não é aceito neste recurso. Para ouvir os eventos das organizações conectadas, a organização da plataforma cria um endpoint com events_from: "platform" usando a própria API key.

Attributes

array

required

Tipos de evento que o endpoint deve receber. Pelo menos um, todos do catálogo público. Tipo desconhecido ou evento organization.* usado com events_from: "organization" retorna 400; duplicados são removidos. Os valores são exatos: wildcards como payment.intent.*, charge.* e * não são aceitos.

string

default:"organization"

Fluxo de eventos que o endpoint ouve. Imutável após a criação — para trocar de fluxo, crie outro endpoint.

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 eventos próprios da organização da plataforma. Veja Fan-out para plataformas.

string

Nome interno para identificar o endpoint no dashboard. Padrão: null.

string

required

URL que recebe as entregas via POST. Em produção precisa ser https; em ambiente de teste http também é aceito.

O que a Chargefy resolve sozinha

secret — gerado no formato whsec_<base64 de 32 bytes aleatórios> e retornado apenas nesta resposta. Não é aceito no payload.
Ambiente — o endpoint nasce no ambiente da API key usada (livemode). Ele só recebe eventos desse ambiente.
events_from — nasce organization quando omitido.

Para receber eventos próprios e eventos das organizações conectadas, crie dois endpoints: um com events_from: "organization" e outro com events_from: "platform". A URL pode ser a mesma, mas cada endpoint tem um secret independente.

curl -X POST "https://api.chargefy.io/v1/webhook-endpoints" \
  -H "Authorization: Bearer {{API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
    "events": ["payment.intent.succeeded", "charge.refunded"],
    "url": "https://meusite.com/webhooks/chargefy"
  }'

curl -X POST "https://api.chargefy.io/v1/webhook-endpoints" \
  -H "Authorization: Bearer {{API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
    "events": ["payment.intent.succeeded", "organization.created"],
    "events_from": "platform",
    "name": "Vendas das organizações conectadas",
    "url": "https://meusite.com/webhooks/chargefy"
  }'

Resposta

200 OK com o objeto webhook_endpoint completo, incluindo o secret — somente aqui.

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

{
  "error": {
    "code": "invalid_request",
    "message": "Unknown event type: payment.succeeded",
    "param": "events",
    "type": "invalid_request_error"
  }
}

{
  "error": {
    "code": "authentication_failed",
    "message": "Unauthorized — invalid api key",
    "type": "authentication_error"
  }
}

Erros

Status	Quando
`400`	`url` ausente, inválida ou `http` em produção; `events` vazio ou com tipo fora do catálogo; evento `organization.*` usado com `events_from: "organization"`; `events_from` inválido; `secret` enviado no payload; `metadata` preenchido (ainda não suportado); header `Organization` enviado.
`401`	Credencial ausente, inválida, revogada ou expirada.
`403`	API key sem escopo `write`, ou API key de plataforma (não gerencia endpoints).

Catálogo de eventos

Valores exatos aceitos em events e payload individual de cada tipo.

Integração com Payment Intents

Inscrição recomendada para os cinco eventos de Payment Intent.

curl -X POST "https://api.chargefy.io/v1/webhook-endpoints" \
  -H "Authorization: Bearer {{API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
    "events": ["payment.intent.succeeded", "charge.refunded"],
    "url": "https://meusite.com/webhooks/chargefy"
  }'

curl -X POST "https://api.chargefy.io/v1/webhook-endpoints" \
  -H "Authorization: Bearer {{API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
    "events": ["payment.intent.succeeded", "organization.created"],
    "events_from": "platform",
    "name": "Vendas das organizações conectadas",
    "url": "https://meusite.com/webhooks/chargefy"
  }'

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

{
  "error": {
    "code": "invalid_request",
    "message": "Unknown event type: payment.succeeded",
    "param": "events",
    "type": "invalid_request_error"
  }
}

{
  "error": {
    "code": "authentication_failed",
    "message": "Unauthorized — invalid api key",
    "type": "authentication_error"
  }
}

Fundamentos da API

Objetos de sistema

Webhooks e eventos

SDKs

MCP

Criar um endpoint de webhook

Autenticação

Attributes

O que a Chargefy resolve sozinha

Resposta

Erros

Catálogo de eventos

Integração com Payment Intents

​Autenticação

​Attributes

​O que a Chargefy resolve sozinha

​Resposta

​Erros

Catálogo de eventos

Integração com Payment Intents

Autenticação

Attributes

O que a Chargefy resolve sozinha

Resposta

Erros