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": []
}
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": []
}'
// 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');
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
$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));
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());
}
}
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());
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))
}
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
(sem corpo)
{
"statusCode": 404,
"message": "Webhook não encontrado",
"error": "Not Found"
}
Webhooks
Atualizar endpoint de webhook
Altera a URL, os eventos habilitados ou a opção de incluir subcontas de um endpoint de webhook.
PUT
/
v1
/
webhook-endpoints
/
{webhookId}
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": []
}
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": []
}'
// 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');
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
$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));
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());
}
}
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());
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))
}
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
(sem corpo)
{
"statusCode": 404,
"message": "Webhook não encontrado",
"error": "Not Found"
}
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.
Mensagens literais da API (trate o erro pelo código HTTP, não pelo texto):
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). A chave age com as permissões do usuário que a gerou: um perfil sem permissão de webhooks recebe403Acesso negado. - Tenha o
iddo endpoint, obtido emGET /v1/webhook-endpoints. - O corpo usa snake_case, como na criação.
Parâmetros de caminho
Corpo da requisição
Todos os campos são opcionais. Envie os que você quer alterar.Novo endereço
http ou https público. Endereços internos e reservados são recusados. Ex.: https://api.meusite.com.br/webhooks/finvia.Lista de eventos que o endpoint recebe. Lista vazia (
[]) recebe todos. Os nomes possíveis estão em Criar endpoint. Incluir charge.updated não tem efeito: ele só vai ao postbackUrl da cobrança.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.
| 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 } |
| 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 |
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": []
}
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": []
}'
// 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');
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
$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));
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());
}
}
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());
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))
}
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
(sem corpo)
{
"statusCode": 404,
"message": "Webhook não encontrado",
"error": "Not Found"
}
Veja também
Listar endpoints
Obtenha o id e confira o resultado.
Excluir endpoint
Pare de enviar eventos para uma URL.
Criar endpoint
Nomes de eventos e regras do cadastro.
Webhooks: visão geral
Quem recebe cada evento e em que formato.

