Gerenciamento de endpoints

Criar, listar, atualizar e apagar endpoints de webhook. Rotacionar segredos sem perder entregas.

Cada organização pode registrar múltiplos endpoints de webhook. Cada endpoint tem a própria URL, o próprio segredo de assinatura e o próprio conjunto de assinaturas (quais eventos quer receber). Esta página é o guia prático de CRUD.

Criar um endpoint

POST /v1/webhook_endpoints HTTP/1.1
Authorization: Bearer sk_test_…
Idempotency-Key: <uuid>
Content-Type: application/json

{
  "url": "https://your-app.example.com/blendfi-webhooks",
  "event_types": [
    "conversion.completed",
    "conversion.completed",
    "conversion.failed",
    "user.kyc_approved"
  ],
  "description": "production handler"
}

curl -X POST $BLENDFI_BASE/v1/webhook_endpoints \
  -H "Authorization: Bearer $BLENDFI_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "content-type: application/json" \
  -d '{
    "url": "https://your-app.example.com/blendfi-webhooks",
    "event_types": ["conversion.completed", "conversion.completed"],
    "description": "production handler"
  }'

import crypto from "node:crypto";

const res = await fetch(`${process.env.BLENDFI_BASE}/v1/webhook_endpoints`, {
  method: "POST",
  headers: {
    "authorization": `Bearer ${process.env.BLENDFI_KEY}`,
    "idempotency-key": crypto.randomUUID(),
    "content-type": "application/json",
  },
  body: JSON.stringify({
    url: "https://your-app.example.com/blendfi-webhooks",
    event_types: ["conversion.completed", "conversion.completed"],
    description: "production handler",
  }),
});
const endpoint = await res.json();
console.log("secret (store securely):", endpoint.secret);

import os, uuid, requests

res = requests.post(
    f"{os.environ['BLENDFI_BASE']}/v1/webhook_endpoints",
    headers={
        "authorization": f"Bearer {os.environ['BLENDFI_KEY']}",
        "idempotency-key": str(uuid.uuid4()),
        "content-type": "application/json",
    },
    json={
        "url": "https://your-app.example.com/blendfi-webhooks",
        "event_types": ["conversion.completed", "conversion.completed"],
        "description": "production handler",
    },
)
endpoint = res.json()
print("secret (store securely):", endpoint["secret"])

A resposta inclui um secret, esta é a única vez em que o segredo em texto plano é retornado. Guarde no seu gerenciador de segredos imediatamente. A BlendFi mantém uma cópia hash para verificação de assinatura, mas não consegue retornar o texto plano de novo.

{
  "id": "we_01J…",
  "url": "https://your-app.example.com/blendfi-webhooks",
  "event_types": ["conversion.completed", "conversion.completed"],
  "secret": "whsec_…",
  "status": "active",
  "description": "production handler",
  "created_at": "2026-05-04T13:00:00Z"
}

Listar endpoints

curl $BLENDFI_BASE/v1/webhook_endpoints \
  -H "Authorization: Bearer $BLENDFI_KEY"

Retorna endpoints paginados. O secret em texto plano não é incluído nas respostas de list ou get.

Atualizar um endpoint

PATCH é parcial, envie apenas os campos que quer mudar.

curl -X PATCH $BLENDFI_BASE/v1/webhook_endpoints/we_01J... \
  -H "Authorization: Bearer $BLENDFI_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "content-type: application/json" \
  -d '{
    "event_types": ["conversion.completed", "conversion.completed", "conversion.failed"],
    "status": "active"
  }'

Patches comuns:

Atualizar assinaturas de evento. Adicione ou remova do array event_types.
Pausar um endpoint. Defina status: "disabled" para parar entregas sem perder a config do endpoint. Volte para "active" para retomar.
Mudar a URL. Use ao migrar entre ambientes.

Apagar um endpoint

curl -X DELETE $BLENDFI_BASE/v1/webhook_endpoints/we_01J... \
  -H "Authorization: Bearer $BLENDFI_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

Soft-delete; as entregas em andamento continuam retentando até esgotar, mas nenhum evento novo é enfileirado.

Rotacionar o secret de assinatura

Rotacionar é a resposta certa para: um host comprometido, um dev saindo do time, uma cadência rotineira (a cada 90 dias, etc.) ou qualquer coisa que cheire estranho.

curl -X POST $BLENDFI_BASE/v1/webhook_endpoints/we_01J.../rotate_secret \
  -H "Authorization: Bearer $BLENDFI_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

Resposta:

{
  "id": "we_01J…",
  "secret": "whsec_NEW…",
  "rotated_at": "2026-05-04T14:00:00Z"
}

Plano de transição

A rotação é uma transição imediata: no instante em que ela termina, o segredo antigo para de funcionar e a BlendFi passa a assinar toda entrega seguinte, incluindo retentativas de eventos anteriores, com o segredo novo. Implante o segredo novo no seu verificador o quanto antes. Como uma entrega assinada com o segredo antigo pode já estar em trânsito até o seu endpoint no momento em que você rotaciona, é prudente aceitar tanto o segredo antigo quanto o novo por alguns segundos durante a troca e então descartar o antigo. Cada header X-Blendfi-Signature carrega um único valor t=<unix>,v1=<hex>, então "aceitar ambos" significa testar cada segredo contra essa única assinatura, não interpretar várias assinaturas no header.

Erros específicos do gerenciamento de endpoint

Descrições completas no catálogo de erros:

Código	Status	Quando
`invalid_webhook_url`	400	URL não é HTTPS ou está mal formada
`invalid_webhook_event_types`	400	Array vazio ou contém nome de evento desconhecido
`max_webhook_endpoints_reached`	422	Organização no limite; apague um endpoint que não esteja em uso
`webhook_endpoint_not_found`	404	ID não existe ou está fora do escopo do tenant
`invalid_webhook_endpoint_state`	422	Operação não permitida no estado atual do endpoint (ex.: aplicar patch em um endpoint apagado)

Leia em seguida

Verificação de assinatura, como verificar entregas no lado receptor
Retentativas e replay, o que acontece quando o seu endpoint não retorna 2xx
Referência → Webhooks, schemas completos para cada operação de gerenciamento de endpoint