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

# Criar endpoint de webhook

> Cadastra um endereço do seu servidor para receber os eventos de cobrança, assinatura e saque de uma conta, com filtro de eventos e a opção de incluir as subcontas.

Esta rota cadastra um endpoint de webhook: a URL do seu servidor que vai receber, por `POST`, os eventos de cobrança, de assinatura e de saque de uma conta. Pela API, você escolhe quais eventos o endpoint recebe. Na conta master do Connect, um único endpoint pode receber também os eventos de todas as subcontas.

## Quando usar

| Situação | Como usar esta rota |
| - | - |
| Receber os eventos da sua conta | `merchantId` com o id da sua conta e `enabled_events: []` para receber todos |
| Receber só alguns eventos | Liste os eventos em `enabled_events`, por exemplo `["charge.paid", "charge.refunded"]` |
| Conta master que quer os eventos de todas as subcontas | Endpoint na master com `include_submerchants: true` |
| Endpoint próprio de uma subconta | A master usa a própria chave secreta com `merchantId` igual ao id da subconta |
| Cadastro sem código | Use o painel, em **Configurações** > **Webhooks**. O endpoint cadastrado pelo painel recebe todos os eventos |

## Antes de chamar

* Use a chave secreta (`sk_`) em Basic ([Credenciais e ambientes](https://docs.fastpaybrasil.com/primeiros-passos/credenciais-e-ambientes.md)). A chave age com as permissões do usuário que a gerou: um perfil sem permissão de webhooks recebe `403` `Acesso negado`.
* Tenha o id da conta que vai receber os eventos. Para uma subconta, consulte [Listar subcontas](https://docs.fastpaybrasil.com/referencia/fast-connect/listar-subcontas.md).
* A URL precisa ser um endereço `http` ou `https` público. Endereços internos e reservados são recusados. Use HTTPS.
* O mesmo endpoint recebe eventos de teste e de produção. Veja [Teste e produção](https://docs.fastpaybrasil.com/guias/webhooks/visao-geral.md#teste-e-produção).

> [!WARNING]
>
> O corpo desta rota usa **snake\_case** (`enabled_events`, `include_submerchants`), diferente do resto da API. Os nomes em camelCase (`enabledEvents`) não são reconhecidos no corpo, embora a listagem devolva os campos em camelCase.

## Parâmetros de consulta

**merchantId** `string` *required*

Id da conta dona do endpoint: a sua própria conta ou, para a conta master, uma das subcontas que ela criou. Obrigatório para credenciais de conta: sem ele, a resposta é `403`. Ex.: `3Fq9TzL2mWc8VbN1xR7pK4hJ6sD`.

## Corpo da requisição

**url** `string` *required*

Endereço `http` ou `https` público que vai receber os eventos. Ex.: `https://meusite.com.br/webhooks/finvia`.

**enabled\_events** `string[]` *required*

Lista de eventos que o endpoint recebe. Lista vazia (`[]`) recebe todos. Nomes possíveis:

* Cobrança: `charge.created`, `charge.pending`, `charge.paid`, `charge.refused`, `charge.failed`, `charge.refunded`, `charge.pre_chargeback`, `charge.blocked`.
* Assinatura: `subscription.created`, `subscription.activated`, `subscription.renewed`, `subscription.payment_failed`, `subscription.cancelled`, `subscription.expired`.
* Saque: `payout.approved`, `payout.rejected`.

O `charge.updated` é entregue só ao `postbackUrl` da cobrança. Incluí-lo aqui não tem efeito.

**include\_submerchants** `boolean`

Só para conta master com Connect habilitado. Com `true`, o endpoint passa a receber também os eventos de cobrança, assinatura e saque das subcontas. O `merchant_id` (ou `merchantId`) de cada payload indica a subconta de origem. Em conta sem Connect, a resposta é `400`.

## Respostas

A resposta de sucesso é `201` **sem corpo**: a API não devolve o id do endpoint. Para obter o id (necessário para editar ou excluir), use [`GET /v1/webhook-endpoints`](https://docs.fastpaybrasil.com/referencia/webhooks/listar-endpoints) com o mesmo `merchantId`.

| HTTP | Significado | Corpo |
| - | - | - |
| `201` | Endpoint criado | Sem corpo |
| `400` | URL inválida, endereço reservado, `include_submerchants` em conta sem Connect ou corpo inválido | `{ statusCode, message, error }`. Nos erros de validação do corpo, `message` é uma lista |
| `401` | Credencial inválida | `{"statusCode": 401, "message": "Unauthorized"}` |
| `403` | Chamada sem `merchantId`, conta sem acesso ou perfil de usuário sem permissão de webhooks | `{ statusCode, message, error }` |
| `404` | Conta não encontrada | `{ statusCode, message, error }` |

Mensagens literais da API. Elas misturam português e inglês e podem mudar: trate o erro pelo código HTTP, não pelo texto.

| HTTP | `message` | Causa |
| - | - | - |
| `400` | `URL inválida: informe um endereço http(s) público (endereços internos e reservados não são permitidos)` | URL fora do formato ou apontando para endereço interno. Quando vem da validação do corpo, chega dentro de uma lista |
| `400` | `Este endereço é reservado e não pode ser usado como destino.` | A URL aponta para um endereço reservado da plataforma |
| `400` | `Apenas contas master com FastConnect habilitado podem receber eventos das subcontas` | `include_submerchants: true` em conta sem Connect |
| `400` | Lista com a descrição do campo inválido | Corpo inválido, por exemplo `enabled_events` que não é lista |
| `403` | `Apenas administradores do gateway podem configurar endpoints de nível gateway` | Chamada sem `merchantId` |
| `403` | `Acesso negado` | Conta a que a credencial não tem acesso, ou perfil de usuário sem permissão de webhooks |
| `404` | `Merchant não encontrado` | `merchantId` inexistente |

## Erros comuns

| Sintoma | Causa | Como resolver |
| - | - | - |
| `403` com "administradores do gateway" | Faltou `merchantId` na query | Envie `?merchantId=` com o id da conta |
| `400` de validação ao enviar `enabledEvents` | O campo obrigatório é `enabled_events`, em snake\_case | Envie `enabled_events` (use `[]` para todos os eventos) |
| `400` com "FastConnect habilitado" | `include_submerchants` em conta sem Connect | Retire o campo ou peça a habilitação do Connect |
| `400` com "URL inválida" | URL local (`localhost`), IP interno ou sem `http(s)` | Use uma URL pública. Em desenvolvimento, exponha a porta local com um túnel como o ngrok |
| Não sei o id do endpoint criado | A resposta `201` não tem corpo | Liste com [`GET /v1/webhook-endpoints`](https://docs.fastpaybrasil.com/referencia/webhooks/listar-endpoints) |
| Eventos chegando duas vezes | Dois endpoints com a mesma URL, ou a mesma URL também usada como `postbackUrl` | Mantenha um cadastro por URL e deduplique os eventos |

```http REST (JSON) theme={null}
POST /v1/webhook-endpoints?merchantId=3Fq9TzL2mWc8VbN1xR7pK4hJ6sD HTTP/1.1
Host: api-global.fastpaybrasil.com
Authorization: Basic <base64 de "SUA_CHAVE_SECRETA:">
Content-Type: application/json

{
  "url": "https://meusite.com.br/webhooks/finvia",
  "enabled_events": [
    "charge.paid",
    "charge.refunded",
    "charge.blocked",
    "payout.approved",
    "payout.rejected"
  ],
  "include_submerchants": true
}
```

```bash cURL theme={null}
curl -X POST "https://api-global.fastpaybrasil.com/v1/webhook-endpoints?merchantId=3Fq9TzL2mWc8VbN1xR7pK4hJ6sD" \
  -u "$FINVIA_API_KEY:" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://meusite.com.br/webhooks/finvia",
    "enabled_events": ["charge.paid", "charge.refunded", "charge.blocked", "payout.approved", "payout.rejected"],
    "include_submerchants": true
  }'
```

```javascript Node.js theme={null}
// criar-endpoint.mjs (Node.js 18+, ESM, await no topo)
const credentials = Buffer.from(`${process.env.FINVIA_API_KEY}:`).toString('base64');
const merchantId = '3Fq9TzL2mWc8VbN1xR7pK4hJ6sD';

const response = await fetch(`https://api-global.fastpaybrasil.com/v1/webhook-endpoints?merchantId=${merchantId}`, {
  method: 'POST',
  headers: {
    Authorization: `Basic ${credentials}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    url: 'https://meusite.com.br/webhooks/finvia',
    enabled_events: [], // lista vazia: todos os eventos
  }),
});

if (response.status !== 201) {
  throw new Error(`Falha ao criar endpoint: ${response.status} ${await response.text()}`);
}
console.log('Endpoint criado');
```

```python Python theme={null}
import os

import requests

payload = {
    "url": "https://meusite.com.br/webhooks/finvia",
    "enabled_events": [
        "charge.paid",
        "charge.refunded",
        "charge.blocked",
        "payout.approved",
        "payout.rejected",
    ],
    "include_submerchants": True,
}

response = requests.request(
    "POST",
    "https://api-global.fastpaybrasil.com/v1/webhook-endpoints?merchantId=3Fq9TzL2mWc8VbN1xR7pK4hJ6sD",
    auth=(os.environ["FINVIA_API_KEY"], ""),
    json=payload,
    timeout=30,
)

print(response.status_code)
if response.content:
    print(response.json())
```

```php PHP theme={null}
<?php

$payload = [
    'url' => 'https://meusite.com.br/webhooks/finvia',
    'enabled_events' => [
        'charge.paid',
        'charge.refunded',
        'charge.blocked',
        'payout.approved',
        'payout.rejected',
    ],
    'include_submerchants' => true,
];

$ch = curl_init('https://api-global.fastpaybrasil.com/v1/webhook-endpoints?merchantId=3Fq9TzL2mWc8VbN1xR7pK4hJ6sD');

curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_USERPWD => getenv('FINVIA_API_KEY') . ':',
    CURLOPT_HTTPHEADER => ['Content-Type: application/json'],
    CURLOPT_POSTFIELDS => json_encode($payload),
]);

$body = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

echo $status, PHP_EOL;
print_r(json_decode($body, true));
```

```java Java theme={null}
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.util.Base64;

public class Exemplo {
    public static void main(String[] args) throws Exception {
        String credentials = Base64.getEncoder()
            .encodeToString((System.getenv("FINVIA_API_KEY") + ":").getBytes());

        String payload = """
            {
              "url": "https://meusite.com.br/webhooks/finvia",
              "enabled_events": [
                "charge.paid",
                "charge.refunded",
                "charge.blocked",
                "payout.approved",
                "payout.rejected"
              ],
              "include_submerchants": true
            }
            """;

        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://api-global.fastpaybrasil.com/v1/webhook-endpoints?merchantId=3Fq9TzL2mWc8VbN1xR7pK4hJ6sD"))
            .header("Authorization", "Basic " + credentials)
            .header("Content-Type", "application/json")
            .method("POST", HttpRequest.BodyPublishers.ofString(payload))
            .build();

        HttpResponse<String> response = HttpClient.newHttpClient()
            .send(request, HttpResponse.BodyHandlers.ofString());

        System.out.println(response.statusCode());
        System.out.println(response.body());
    }
}
```

```csharp C# theme={null}
using System.Net.Http.Headers;
using System.Text;

var apiKey = Environment.GetEnvironmentVariable("FINVIA_API_KEY");
var credentials = Convert.ToBase64String(Encoding.UTF8.GetBytes($"{apiKey}:"));

using var client = new HttpClient();
client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Basic", credentials);

var payload = """
{
  "url": "https://meusite.com.br/webhooks/finvia",
  "enabled_events": [
    "charge.paid",
    "charge.refunded",
    "charge.blocked",
    "payout.approved",
    "payout.rejected"
  ],
  "include_submerchants": true
}
""";

var request = new HttpRequestMessage(HttpMethod.Post, "https://api-global.fastpaybrasil.com/v1/webhook-endpoints?merchantId=3Fq9TzL2mWc8VbN1xR7pK4hJ6sD");
request.Content = new StringContent(payload, Encoding.UTF8, "application/json");

var response = await client.SendAsync(request);
Console.WriteLine((int)response.StatusCode);
Console.WriteLine(await response.Content.ReadAsStringAsync());
```

```go Go theme={null}
package main

import (
	"fmt"
	"io"
	"net/http"
	"os"
	"strings"
)

func main() {
	payload := strings.NewReader(`{
	  "url": "https://meusite.com.br/webhooks/finvia",
	  "enabled_events": [
	    "charge.paid",
	    "charge.refunded",
	    "charge.blocked",
	    "payout.approved",
	    "payout.rejected"
	  ],
	  "include_submerchants": true
	}`)

	req, err := http.NewRequest("POST", "https://api-global.fastpaybrasil.com/v1/webhook-endpoints?merchantId=3Fq9TzL2mWc8VbN1xR7pK4hJ6sD", payload)
	if err != nil {
		panic(err)
	}
	req.SetBasicAuth(os.Getenv("FINVIA_API_KEY"), "")
	req.Header.Set("Content-Type", "application/json")

	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()

	body, _ := io.ReadAll(res.Body)
	fmt.Println(res.StatusCode)
	fmt.Println(string(body))
}
```

```ruby Ruby theme={null}
require "json"
require "net/http"
require "uri"

uri = URI("https://api-global.fastpaybrasil.com/v1/webhook-endpoints?merchantId=3Fq9TzL2mWc8VbN1xR7pK4hJ6sD")
request = Net::HTTP::Post.new(uri)
request.basic_auth(ENV.fetch("FINVIA_API_KEY"), "")
request["Content-Type"] = "application/json"
request.body = JSON.generate({
  "url" => "https://meusite.com.br/webhooks/finvia",
  "enabled_events" => [
    "charge.paid",
    "charge.refunded",
    "charge.blocked",
    "payout.approved",
    "payout.rejected",
  ],
  "include_submerchants" => true,
})

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
  http.request(request)
end

puts response.code
puts response.body
```

```text 201 theme={null}
(sem corpo)
```

```json 400 URL inválida theme={null}
{
  "statusCode": 400,
  "message": [
    "URL inválida: informe um endereço http(s) público (endereços internos e reservados não são permitidos)"
  ],
  "error": "Bad Request"
}
```

```json 400 Sem Connect theme={null}
{
  "statusCode": 400,
  "message": "Apenas contas master com FastConnect habilitado podem receber eventos das subcontas",
  "error": "Bad Request"
}
```

```json 403 Sem merchantId theme={null}
{
  "statusCode": 403,
  "message": "Apenas administradores do gateway podem configurar endpoints de nível gateway",
  "error": "Forbidden"
}
```

```json 404 theme={null}
{
  "statusCode": 404,
  "message": "Merchant não encontrado",
  "error": "Not Found"
}
```

## Veja também

> [card] [Listar endpoints](https://docs.fastpaybrasil.com/referencia/webhooks/listar-endpoints.md)
>
> Obtenha o id e confira os eventos de cada endpoint.

> [card] [Atualizar endpoint](https://docs.fastpaybrasil.com/referencia/webhooks/atualizar-endpoint.md)
>
> Troque a URL ou os eventos.

> [card] [Webhooks: visão geral](https://docs.fastpaybrasil.com/guias/webhooks/visao-geral.md)
>
> Quem recebe cada evento, formatos e deduplicação.

> [card] [Catálogo de eventos](https://docs.fastpaybrasil.com/anexos/catalogo-de-eventos.md)
>
> Todos os eventos e quando são enviados.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.