> ## Documentation Index
> Fetch the complete documentation index at: https://docs.chargefy.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Endpoints de webhooks

> Contrato do webhook_endpoint: tipos exatos inscritos, events_from para organização ou plataforma, ambiente, URL e secret Standard Webhooks.

Um `webhook_endpoint` é uma URL sua que a Chargefy chama quando os [eventos](/api-reference/events/types) que você assinou acontecem. Cada endpoint tem um `secret` próprio para [verificar a assinatura](/integrate/webhooks/delivery#verificação) 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](/integrate/webhooks/delivery#fan-out-para-plataformas).

<Warning>
  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"`.
</Warning>

## 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](/integrate/webhooks/delivery#rotação-de-secret-e-múltiplas-assinaturas).

## Data Object

```json theme={"theme":"css-variables"}
{
  "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"
}
```

<ResponseField name="id" type="string">
  Identificador do endpoint. Usa o prefixo `we_*`.
</ResponseField>

<ResponseField name="object" type="string">
  Sempre `"webhook_endpoint"`.
</ResponseField>

<ResponseField name="created_at" type="string">
  Data de criação em ISO 8601.
</ResponseField>

<ResponseField name="events" type="array">
  Tipos de evento que o endpoint recebe. Só eventos do [catálogo público](/api-reference/events/types) são aceitos. Os valores são comparados por igualdade; não há expansão de wildcard.
</ResponseField>

<ResponseField name="events_from" type="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. |
</ResponseField>

<ResponseField name="livemode" type="boolean">
  `true` em produção; `false` em ambiente de teste. Definido pelo ambiente da API key usada na criação.
</ResponseField>

<ResponseField name="metadata" type="object">
  Reservado. Endpoints de webhook ainda não aceitam metadata; retorna sempre `{}`.
</ResponseField>

<ResponseField name="name" type="string | null">
  Nome interno para identificar o endpoint no dashboard.
</ResponseField>

<ResponseField name="updated_at" type="string | null">
  Data da última atualização em ISO 8601.
</ResponseField>

<ResponseField name="url" type="string">
  URL que recebe as entregas via `POST`. Em produção precisa ser `https`.
</ResponseField>

## Operações

* [Listar endpoints de webhook](/api-reference/webhook-endpoints/list)
* [Criar endpoint de webhook](/api-reference/webhook-endpoints/create)
* [Consultar endpoint de webhook](/api-reference/webhook-endpoints/get)
* [Atualizar endpoint de webhook](/api-reference/webhook-endpoints/update)
* [Remover endpoint de webhook](/api-reference/webhook-endpoints/delete)

## Para Payment Intents

Cadastre explicitamente:

```json theme={"theme":"css-variables"}
[
  "payment.intent.created",
  "payment.intent.updated",
  "payment.intent.succeeded",
  "payment.intent.canceled"
]
```

<CardGroup cols={2}>
  <Card title="Criar endpoint" icon="plus" href="/api-reference/webhook-endpoints/create">
    Exemplos para organização e plataforma.
  </Card>

  <Card title="Entrega e assinatura" icon="signature" href="/integrate/webhooks/delivery">
    Headers oficiais, timeout, retries, duplicação, ordem e fan-out.
  </Card>
</CardGroup>