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

# Atualizar endpoint de webhook

> Altera a URL, os eventos habilitados ou a opção de incluir subcontas de um endpoint de webhook.

Esta rota altera um endpoint de webhook já cadastrado. Use-a para trocar a URL de recebimento (por exemplo, numa migração de servidor), ajustar a lista de eventos ou ligar e desligar o recebimento dos eventos das subcontas.

## Quando usar

| Situação | O que enviar |
| - | - |
| Trocar o servidor que recebe os eventos | `url` |
| Passar a receber todos os eventos | `enabled_events: []` |
| Restringir aos eventos que a sua aplicação trata | `enabled_events` com a lista desejada |
| Conta master que quer, ou não quer mais, os eventos das subcontas | `include_submerchants` |

## 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` do endpoint, obtido em [`GET /v1/webhook-endpoints`](https://docs.fastpaybrasil.com/referencia/webhooks/listar-endpoints).
* O corpo usa **snake\_case**, como na criação.

## Parâmetros de caminho

**webhookId** `string` *required*

Id do endpoint, o campo `id` da listagem. Ex.: `2wHn5Qe8rT1yU4iO7pA3sD6fG9k`.

## Corpo da requisição

Todos os campos são opcionais. Envie os que você quer alterar.

**url** `string`

Novo endereço `http` ou `https` público. Endereços internos e reservados são recusados. Ex.: `https://api.meusite.com.br/webhooks/finvia`.

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

Lista de eventos que o endpoint recebe. Lista vazia (`[]`) recebe todos. Os nomes possíveis estão em [Criar endpoint](https://docs.fastpaybrasil.com/referencia/webhooks/criar-endpoint.md). Incluir `charge.updated` não tem efeito: ele só vai ao `postbackUrl` da cobrança.

**include\_submerchants** `boolean`

Só para conta master com Connect habilitado. Com `true`, o endpoint recebe também os eventos das subcontas; com `false`, deixa de receber.

## Respostas

A resposta de sucesso é `200` **sem corpo**. Para conferir o resultado, use [`GET /v1/webhook-endpoints`](https://docs.fastpaybrasil.com/referencia/webhooks/listar-endpoints).

| HTTP | Significado | Corpo |
| - | - | - |
| `200` | Endpoint atualizado | 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` | Endpoint de conta sem acesso ou perfil de usuário sem permissão de webhooks | `{ statusCode, message, error }` |
| `404` | Endpoint não encontrado | `{ statusCode, message, error }` |

Mensagens literais da API (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 |
| `403` | `Acesso negado` | Conta a que a credencial não tem acesso, ou perfil de usuário sem permissão de webhooks |
| `404` | `Webhook não encontrado` | `webhookId` inexistente |

## Erros comuns

| Sintoma | Causa | Como resolver |
| - | - | - |
| `404` `Webhook não encontrado` | Id errado ou endpoint já excluído | Liste os endpoints e use o `id` atual |
| Eventos de subconta continuam chegando | O mesmo endereço também está cadastrado direto na subconta | Liste os endpoints da subconta e exclua o cadastro duplicado |
| `400` com "FastConnect habilitado" | `include_submerchants: true` em conta sem Connect | Retire o campo |

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

{
  "url": "https://api.meusite.com.br/webhooks/finvia",
  "enabled_events": []
}
```

```bash cURL theme={null}
curl -X PUT "https://api-global.fastpaybrasil.com/v1/webhook-endpoints/2wHn5Qe8rT1yU4iO7pA3sD6fG9k" \
  -u "$FINVIA_API_KEY:" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://api.meusite.com.br/webhooks/finvia",
    "enabled_events": []
  }'
```

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

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

if (response.status !== 200) {
  throw new Error(`Falha ao atualizar: ${response.status} ${await response.text()}`);
}
console.log('Endpoint atualizado');
```

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

import requests

payload = {
    "url": "https://api.meusite.com.br/webhooks/finvia",
    "enabled_events": [],
}

response = requests.request(
    "PUT",
    "https://api-global.fastpaybrasil.com/v1/webhook-endpoints/2wHn5Qe8rT1yU4iO7pA3sD6fG9k",
    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://api.meusite.com.br/webhooks/finvia',
    'enabled_events' => [],
];

$ch = curl_init('https://api-global.fastpaybrasil.com/v1/webhook-endpoints/2wHn5Qe8rT1yU4iO7pA3sD6fG9k');

curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'PUT',
    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://api.meusite.com.br/webhooks/finvia",
              "enabled_events": []
            }
            """;

        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://api-global.fastpaybrasil.com/v1/webhook-endpoints/2wHn5Qe8rT1yU4iO7pA3sD6fG9k"))
            .header("Authorization", "Basic " + credentials)
            .header("Content-Type", "application/json")
            .method("PUT", 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://api.meusite.com.br/webhooks/finvia",
  "enabled_events": []
}
""";

var request = new HttpRequestMessage(HttpMethod.Put, "https://api-global.fastpaybrasil.com/v1/webhook-endpoints/2wHn5Qe8rT1yU4iO7pA3sD6fG9k");
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://api.meusite.com.br/webhooks/finvia",
	  "enabled_events": []
	}`)

	req, err := http.NewRequest("PUT", "https://api-global.fastpaybrasil.com/v1/webhook-endpoints/2wHn5Qe8rT1yU4iO7pA3sD6fG9k", 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/2wHn5Qe8rT1yU4iO7pA3sD6fG9k")
request = Net::HTTP::Put.new(uri)
request.basic_auth(ENV.fetch("FINVIA_API_KEY"), "")
request["Content-Type"] = "application/json"
request.body = JSON.generate({
  "url" => "https://api.meusite.com.br/webhooks/finvia",
  "enabled_events" => [],
})

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

puts response.code
puts response.body
```

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

```json 404 theme={null}
{
  "statusCode": 404,
  "message": "Webhook 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 o resultado.

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

> [card] [Criar endpoint](https://docs.fastpaybrasil.com/referencia/webhooks/criar-endpoint.md)
>
> Nomes de eventos e regras do cadastro.

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