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

# Listar endpoints de webhook

> Lista os endpoints de webhook de uma conta, com a URL, os eventos habilitados e a opção de incluir subcontas de cada um.

Esta rota lista os endpoints de webhook cadastrados em uma conta, pelo painel ou pela API. É por ela que você descobre o `id` de um endpoint, necessário para editar ou excluir, e confere quais eventos cada um recebe.

## Quando usar

| Situação | Como usar esta rota |
| - | - |
| Descobrir o `id` do endpoint que você acabou de criar | `POST /v1/webhook-endpoints` responde sem corpo. Liste com o mesmo `merchantId` |
| Auditar quais URLs recebem os eventos da conta | Liste e confira `url`, `enabledEvents` e `includeSubmerchants` |
| Conferir os endpoints de uma subconta (conta master) | Use `merchantId` igual ao id da subconta |
| Achar um endpoint específico | Use `search` |

## 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: a sua própria ou, para a conta master, o de uma subconta que ela criou.

## Parâmetros de consulta

**merchantId** `string` *required*

Id da conta cujos endpoints serão listados. Obrigatório para credenciais de conta: sem ele, a resposta é `403`. Ex.: `3Fq9TzL2mWc8VbN1xR7pK4hJ6sD`.

**search** `string`

Termo de busca. Ex.: `meusite`.

**page** `integer`

Número da página, começando em `1`.

**size** `integer`

Quantidade de itens por página. Ex.: `20`.

## Respostas

A resposta `200` traz a página de endpoints e os totais. Diferente do corpo da criação, os itens vêm em **camelCase**.

**data** `object[]` *required*

Endpoints da página.

**propriedades**

**id** `string`

Id do endpoint. É o `webhookId` usado para atualizar e excluir.

**url** `string`

URL que recebe os eventos.

**merchantId** `string`

Conta dona do endpoint.

**enabledEvents** `string[]`

Eventos habilitados. Lista vazia significa todos.

**includeSubmerchants** `boolean`

`true` se o endpoint também recebe os eventos das subcontas.

**gatewayId** `string`

Identificador do gateway ao qual a conta pertence.

**createdAt** `string`

Data e hora de criação (ISO 8601).

**updatedAt** `string`

Data e hora da última alteração (ISO 8601).

**deletedAt** `string | null`

Data e hora de exclusão, quando houver.

**total** `integer` *required*

Total de endpoints que atendem aos filtros, somando todas as páginas.

**page** `integer` *required*

Página devolvida.

**size** `integer` *required*

Itens por página.

**pages** `integer` *required*

Total de páginas.

| HTTP | Significado | Corpo |
| - | - | - |
| `200` | Lista devolvida | `{ data, total, page, size, pages }` |
| `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 (trate o erro pelo código HTTP, não pelo texto):

| HTTP | `message` | Causa |
| - | - | - |
| `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 |
| Lista vazia na subconta, mas a master recebe os eventos | O endpoint está cadastrado na master, com `includeSubmerchants: true` | Liste com o `merchantId` da master |
| Código lendo `enabled_events` na resposta | A resposta usa camelCase | Leia `enabledEvents` e `includeSubmerchants` |

```http REST (JSON) theme={null}
GET /v1/webhook-endpoints?merchantId=3Fq9TzL2mWc8VbN1xR7pK4hJ6sD&page=1&size=20 HTTP/1.1
Host: api-global.fastpaybrasil.com
Authorization: Basic <base64 de "SUA_CHAVE_SECRETA:">
```

```bash cURL theme={null}
curl -X GET "https://api-global.fastpaybrasil.com/v1/webhook-endpoints?merchantId=3Fq9TzL2mWc8VbN1xR7pK4hJ6sD&page=1&size=20" \
  -u "$FINVIA_API_KEY:"
```

```javascript Node.js theme={null}
// listar-endpoints.mjs (Node.js 18+, ESM, await no topo)
const credentials = Buffer.from(`${process.env.FINVIA_API_KEY}:`).toString('base64');
const params = new URLSearchParams({ merchantId: '3Fq9TzL2mWc8VbN1xR7pK4hJ6sD', page: '1', size: '20' });

const response = await fetch(`https://api-global.fastpaybrasil.com/v1/webhook-endpoints?${params}`, {
  headers: { Authorization: `Basic ${credentials}` },
});

const { data, total } = await response.json();
console.log(`${total} endpoint(s)`);
for (const endpoint of data) {
  console.log(endpoint.id, endpoint.url, endpoint.enabledEvents, endpoint.includeSubmerchants);
}
```

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

import requests

response = requests.request(
    "GET",
    "https://api-global.fastpaybrasil.com/v1/webhook-endpoints?merchantId=3Fq9TzL2mWc8VbN1xR7pK4hJ6sD&page=1&size=20",
    auth=(os.environ["FINVIA_API_KEY"], ""),
    timeout=30,
)

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

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

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

curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'GET',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_USERPWD => getenv('FINVIA_API_KEY') . ':',
]);

$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());

        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://api-global.fastpaybrasil.com/v1/webhook-endpoints?merchantId=3Fq9TzL2mWc8VbN1xR7pK4hJ6sD&page=1&size=20"))
            .header("Authorization", "Basic " + credentials)
            .method("GET", HttpRequest.BodyPublishers.noBody())
            .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 request = new HttpRequestMessage(HttpMethod.Get, "https://api-global.fastpaybrasil.com/v1/webhook-endpoints?merchantId=3Fq9TzL2mWc8VbN1xR7pK4hJ6sD&page=1&size=20");

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"
)

func main() {
	req, err := http.NewRequest("GET", "https://api-global.fastpaybrasil.com/v1/webhook-endpoints?merchantId=3Fq9TzL2mWc8VbN1xR7pK4hJ6sD&page=1&size=20", nil)
	if err != nil {
		panic(err)
	}
	req.SetBasicAuth(os.Getenv("FINVIA_API_KEY"), "")

	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 "net/http"
require "uri"

uri = URI("https://api-global.fastpaybrasil.com/v1/webhook-endpoints?merchantId=3Fq9TzL2mWc8VbN1xR7pK4hJ6sD&page=1&size=20")
request = Net::HTTP::Get.new(uri)
request.basic_auth(ENV.fetch("FINVIA_API_KEY"), "")

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

puts response.code
puts response.body
```

```json 200 theme={null}
{
  "data": [
    {
      "id": "2wHn5Qe8rT1yU4iO7pA3sD6fG9k",
      "url": "https://meusite.com.br/webhooks/finvia",
      "merchantId": "3Fq9TzL2mWc8VbN1xR7pK4hJ6sD",
      "enabledEvents": ["charge.paid", "charge.refunded", "charge.blocked", "payout.approved", "payout.rejected"],
      "includeSubmerchants": true,
      "gatewayId": "2bGt4Yh7Uj1Ik5Ol8Pz3Xc6Vb9N",
      "createdAt": "2026-10-20T13:45:00.000Z",
      "updatedAt": "2026-10-20T13:45:00.000Z",
      "deletedAt": null
    }
  ],
  "total": 1,
  "page": 1,
  "size": 20,
  "pages": 1
}
```

```json 403 theme={null}
{
  "statusCode": 403,
  "message": "Acesso negado",
  "error": "Forbidden"
}
```

## Veja também

> [card] [Criar endpoint](https://docs.fastpaybrasil.com/referencia/webhooks/criar-endpoint.md)
>
> Cadastre um endpoint com filtro de eventos.

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

> [card] [Excluir endpoint](https://docs.fastpaybrasil.com/referencia/webhooks/excluir-endpoint.md)
>
> Pare de enviar eventos para uma URL.

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


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