clerk/clerk-webhooks

O que clerk-webhooks faz?

Webhooks do Clerk para eventos em tempo real e sincronização de dados. Verifique com o verifyWebhook do pacote específico do framework. Lide com eventos de usuário, sessão, organização, cobrança e pagamento. Construa funcionalidades orientadas a eventos como sincronização de banco de dados, notificações e integrações.

Visão Geral

Os webhooks do Clerk permitem que você receba notificações em tempo real sobre eventos que ocorrem na sua instância do Clerk, como criação/atualização/exclusão de usuários, sessões e organizações. Eles são essenciais para sincronizar dados com sistemas externos (banco de dados próprio, CRM, etc.), disparar notificações, ou integrar com outros serviços.

Como Funciona

1. Configure um endpoint HTTP (rota de API) no seu servidor para receber eventos.
2. O Clerk envia uma requisição POST com payload JSON para esse endpoint sempre que um evento ocorre.
3. Cada requisição inclui um cabeçalho svix-signature que deve ser verificado usando o segredo do webhook (CLERK_WEBHOOK_SECRET).
4. Use a função verifyWebhook do pacote específico do seu framework para validar a assinatura.
5. Processe o evento baseado no campo type do payload.

Plataformas Suportadas

• Next.js: @clerk/nextjs
• Express: @clerk/express
• Fastify: @clerk/fastify
• Redwood: @clerk/redwood
• Remix: @clerk/remix
• Vue: @clerk/vue
• Nuxt: @clerk/nuxt

Eventos Disponíveis

Os principais eventos que você pode escutar incluem:

• user.created
• user.updated
• user.deleted
• session.created
• session.ended
• session.removed
• organization.created
• organization.updated
• organization.deleted
• organizationMembership.created
• organizationMembership.updated
• organizationMembership.deleted
• billing.created
• billing.updated
• payment.created

Exemplo de Implementação (Next.js)

// app/api/webhooks/route.ts
import { Webhook } from 'svix';
import { headers } from 'next/headers';
import { WebhookEvent } from '@clerk/nextjs/server';

export async function POST(req: Request) {
  const WEBHOOK_SECRET = process.env.CLERK_WEBHOOK_SECRET;

  if (!WEBHOOK_SECRET) {
    throw new Error('CLERK_WEBHOOK_SECRET não está definido');
  }

  // Obter cabeçalhos
  const headerPayload = headers();
  const svixId = headerPayload.get('svix-id');
  const svixTimestamp = headerPayload.get('svix-timestamp');
  const svixSignature = headerPayload.get('svix-signature');

  if (!svixId || !svixTimestamp || !svixSignature) {
    return new Response('Cabeçalhos svix ausentes', { status: 400 });
  }

  const payload = await req.json();
  const body = JSON.stringify(payload);

  const wh = new Webhook(WEBHOOK_SECRET);
  let evt: WebhookEvent;

  try {
    evt = wh.verify(body, {
      'svix-id': svixId,
      'svix-timestamp': svixTimestamp,
      'svix-signature': svixSignature,
    }) as WebhookEvent;
  } catch (err) {
    console.error('Falha na verificação do webhook:', err);
    return new Response('Verificação falhou', { status: 400 });
  }

  const eventType = evt.type;

  // Processar eventos
  switch (eventType) {
    case 'user.created':
      console.log('Usuário criado:', evt.data.id);
      // Sincronizar com banco de dados
      break;
    case 'user.updated':
      console.log('Usuário atualizado:', evt.data.id);
      break;
    case 'organization.created':
      console.log('Organização criada:', evt.data.id);
      break;
    default:
      console.log('Tipo de evento não tratado:', eventType);
  }

  return new Response('Recebido', { status: 200 });
}

Variáveis de Ambiente

• CLERK_WEBHOOK_SECRET: Segredo obtido no Dashboard do Clerk (configuração do webhook).

Boas Práticas

• Verificação obrigatória: Sempre verifique a assinatura do webhook para evitar eventos falsificados.
• Idempotência: Processe eventos de forma idempotente (use id do evento para evitar duplicatas).
• Tratamento de erros: Capture e registre erros, mas sempre retorne 200 para evitar reenvios desnecessários.
• Timeout curto: Responda rapidamente (200) para não bloquear o Clerk. Para tarefas lentas, use filas ou workers assíncronos.

Recursos Adicionais

• Documentação oficial do Clerk sobre webhooks
• Svix documentação (Clerk usa Svix como backend de webhook)