> ## 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.

# Criar um endpoint de webhook

> Registra uma URL para receber tipos exatos de eventos da organização ou de organizações conectadas e retorna o secret Standard Webhooks uma única vez.

Cria um `webhook_endpoint`. A resposta é a **única** vez que o `secret` aparece — guarde-o para [verificar as assinaturas](/integrate/webhooks/delivery#verificação) das entregas.

**Obrigatórios: `url` e `events`.** Todo o resto tem default.

Este endpoint aceita [`Idempotency-Key`](/api-reference/idempotency).

## 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

<ParamField body="events" type="array" required>
  Tipos de evento que o endpoint deve receber. Pelo menos um, todos do [catálogo público](/api-reference/events/types). 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.
</ParamField>

<ParamField body="events_from" default="organization" type="string">
  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](/integrate/webhooks/delivery#fan-out-para-plataformas). |
</ParamField>

<ParamField body="name" type="string">
  Nome interno para identificar o endpoint no dashboard. Padrão: `null`.
</ParamField>

<ParamField body="url" type="string" required>
  URL que recebe as entregas via `POST`. Em produção precisa ser `https`; em ambiente de teste `http` também é aceito.
</ParamField>

## 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.

<Note>
  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.
</Note>

<RequestExample>
  ```bash Mínimo theme={"theme":"css-variables"}
  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"
    }'
  ```

  ```bash Fluxo de plataforma theme={"theme":"css-variables"}
  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"
    }'
  ```
</RequestExample>

## Resposta

`200 OK` com o objeto [`webhook_endpoint`](/api-reference/webhook-endpoints/object) completo, incluindo o `secret` — **somente aqui**.

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

  ```json 400 theme={"theme":"css-variables"}
  {
    "error": {
      "code": "invalid_request",
      "message": "Unknown event type: payment.succeeded",
      "param": "events",
      "type": "invalid_request_error"
    }
  }
  ```

  ```json 401 theme={"theme":"css-variables"}
  {
    "error": {
      "code": "authentication_failed",
      "message": "Unauthorized — invalid api key",
      "type": "authentication_error"
    }
  }
  ```
</ResponseExample>

## 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).                                                                                                                                                                                                                |

<CardGroup cols={2}>
  <Card title="Catálogo de eventos" icon="list" href="/api-reference/events/types">
    Valores exatos aceitos em `events` e payload individual de cada tipo.
  </Card>

  <Card title="Integração com Payment Intents" icon="credit-card" href="/payments/accept-payments-with-payment-intents">
    Inscrição recomendada para os cinco eventos de Payment Intent.
  </Card>
</CardGroup>