---
title: "Webhooks"
description: "Assine eventos implementados de usuário, organização, associação, convite e certificado SAML por meio de entregas HTTP assinadas."
locale: "pt-BR"
---

> Documentation Index
> Fetch the relevant documentation index at: https://vonvon.id/pt-br/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks

## Nomenclatura de eventos

Os eventos implementados seguem o padrão `<object>.<action>`. O header vonvon-webhook-event e o type do body contêm o nome exato do evento; cada entrega também tem um `svix-id` exclusivo.

| Objeto | Ações |
| --- | --- |
| `user` | created, updated, deleted, restored, banned, unbanned, deactivated |
| `organization` | created, updated, deleted, restored |
| `organization.auth_policy` | atualizado |
| `organization.delivery_channels` | atualizado |
| `organization.social_providers` | atualizado |
| `organization.outbound_saml_app` | created, deleted |
| `organization.scim_target` | created, deleted |
| `organizationMembership` | created, updated, deleted, restored |
| `organizationInvitation` | created, accepted, revoked |
| `connection` | saml\_certificate\_renewed |
| `user.*` | Curinga de assinatura para todos os eventos de usuário implementados. |
| `organization.*` | Curinga de assinatura para todos os eventos da organização implementados, incluindo subeventos pontilhados. |
| `organizationMembership.*` | Curinga de assinatura para todos os eventos de associação da organização implementados. |
| `*` | Curinga de assinatura para cada evento implementado. |

## Estrutura do payload

Cada entrega de webhook é um HTTP POST com `Content-Type: application/json`. O corpo contém o evento exato `type` e seu `data`; Os metadados svix são transportados em cabeçalhos de solicitação.

```json
{
  "type": "user.created",
  "data": {
"userId": "user_01abc"
  }
}
```

## Verificação de assinatura

O Vonvon assina cada entrega com HMAC-SHA256. Verifique a assinatura antes de processar o payload. Rejeite entregas com mais de 5 minutos para evitar ataques de replay.

| Cabeçalho | Descrição |
| --- | --- |
| `svix-id` | ID de mensagem único. Use para deduplicar entregas repetidas. |
| `svix-timestamp` | Segundos Unix em que a mensagem foi enviada. |
| `svix-signature` | O cabeçalho svix-signature começa com o prefixo literal v1, seguido pelo HMAC-SHA256 codificado em Base64 de `${svix-id}.${svix-timestamp}.${raw-body}` usando o segredo de assinatura do terminal. |

```ts
import { verifyWebhook } from '@vonvon-kit/backend'

const result = await verifyWebhook(request, {
  secret: env.VONVON_WEBHOOK_SECRET,
})
if (!result.ok) {
  return new Response('Invalid webhook', { status: 400 })
}
const { type, data } = result.value.payload
```

## Tentativas e dead letters

- As tentativas de entrega usam backoff exponencial e terminam com o status dead. Quando a fila se esgota, a mensagem original é armazenada de forma criptografada para que um Instance Manager possa inspecioná-la e reenviá-la.
- A entrega é desacoplada do caminho de autenticação via Cloudflare Queues. Um endpoint lento ou indisponível não afeta a latência de login.
- Use o cabeçalho `svix-id` para deduplicar entregas no seu lado. As tentativas carregam o mesmo `svix-id` da tentativa original.

```mermaid
flowchart LR
  Vonvon --> Queue
  Queue -->|HTTPS| Endpoint
  Endpoint -->|2xx| ACK
  Endpoint -->|non-2xx| Retry
  Retry --> Queue
  Retry -->|max_retries| dlq["D1 DLQ"]
```

## Recuperação de endpoint

Use `POST /v1/webhooks/:id/restore` para reativar um endpoint excluído e `POST /v1/webhooks/:id/rotate-secret` para substituir seu segredo de assinatura. O novo `signing_secret` é retornado uma vez. A reprodução no nível do produto por ID de entrega ou `time range` não está implementada.

```shell
curl -X POST https://vonvon.id/v1/webhooks/webhook_xxx/rotate-secret \
  -H 'Authorization: Bearer sk_live_xxx'
```

## Limite do histórico de entrega

O Vonvon não expõe uma Events API de consulta. Use `GET /v1/webhooks` para gerenciar assinaturas. O estado das entregas e o reenvio da fila de mensagens não entregues são superfícies operacionais para Instance Managers, não um fluxo de eventos do tenant.

```shell
curl 'https://vonvon.id/v1/webhooks?limit=100' \
  -H 'Authorization: Bearer sk_live_xxx'
```

Source: https://vonvon.id/pt-br/webhooks/index.mdx