# Clerk + Brew

Dispare automações do Brew a partir de eventos de webhook do Clerk referentes a cadastros de usuários, mudanças na organização, assinaturas pagas e entradas na lista de espera.

URL canônica: https://brew.new/pt-br/browse/integrations/clerk

- Direção: Entrada de dados
- Conexão: Segredo de webhook
- Gatilhos de eventos de autenticação

## Funcionalidades disponíveis

- **Gatilhos de evento**: Dispare automações do Brew a partir de 13 eventos de webhook do Clerk, nas categorias usuário, organização, cobrança e lista de espera.

## Transforme eventos do Clerk em e-mails úteis

Conecte o Clerk para disparar e-mails com a cara da sua marca quando alguém se cadastra, passa a fazer parte de uma organização, inicia uma assinatura do Clerk Billing ou entra na sua lista de espera. O Clerk assina cada webhook, e o Brew transforma 13 tipos de evento em gatilhos de automação.

O Clerk continua responsável pelo login, pelas organizações e pela cobrança. O Brew só escuta os eventos: ele não pode alterar usuários, criar organizações nem cobrar assinaturas.


## O que você pode criar

- E-mails de boas-vindas: o evento user.created é disparado quando um novo usuário se cadastra. Os campos username, imageUrl e lastSignInAt ficam disponíveis junto com o nome.
- Onboarding de equipes: o evento organizationMembership.created traz organizationName, organizationSlug e roleName do novo membro, quer ele tenha aceitado um convite, quer tenha sido adicionado diretamente. O organizationInvitation.accepted também é disparado quando um convite é aceito, então escolha um único gatilho para evitar boas-vindas duplicadas.
- Acompanhamento de convites: os eventos organizationInvitation.created, organizationInvitation.accepted e organizationInvitation.revoked vão para o endereço convidado e trazem roleName, status e expiresAt. Eles não trazem o nome da organização, quem fez o convite nem um link para aceitá-lo.
- E-mails de boas-vindas para assinantes: o evento subscription.created traz planName, planSlug, planAmount, currency, periodStart e periodEnd.
- Lembretes de fim do período de teste: o evento subscriptionItem.freeTrialEnding é disparado pouco antes de um teste grátis do Clerk Billing virar uma assinatura paga, com planName, planAmount, currency e periodEnd.
- Avisos de pagamento em atraso: o evento subscriptionItem.pastDue é disparado quando um item de assinatura fica com um pagamento em atraso. Inclua um link para a sua própria página de cobrança.
- E-mails após cancelamentos e testes abandonados: o evento subscriptionItem.canceled é disparado quando um item é cancelado. O subscriptionItem.abandoned normalmente indica que um período de teste terminou sem uma forma de pagamento cadastrada.
- Confirmações de entrada na lista de espera: o evento waitlistEntry.created é disparado quando um endereço de e-mail entra na sua lista de espera do Clerk.

## Eventos de organização precisam de um criador conhecido

O evento organization.created não traz nenhum endereço de e-mail. O Brew procura o ID de usuário do criador entre as identidades que já viu em eventos anteriores do Clerk, na conexão atual. Se encontrar um e-mail real, o evento segue adiante. Se não, o Brew registra o evento com um destinatário não resolvido, não cria nenhum contato e não inicia nenhuma automação.

Inscreva o endpoint também no user.created, para que o Brew conheça os endereços dos criadores. Para um e-mail que precisa chegar a uma pessoa todas as vezes, use o organizationMembership.created, que traz o endereço do membro.


## Configure o Clerk no Brew

- Abra Integrações, escolha Clerk e selecione Gerar URL do webhook.
- No painel do Clerk, abra Webhooks e adicione um endpoint com a URL do Brew.
- Inscreva o endpoint nos 13 eventos compatíveis dos grupos user, organization, organizationInvitation, organizationMembership, paymentAttempt, subscription, subscriptionItem e waitlistEntry e, depois, crie o endpoint.
- Mostre o segredo de assinatura do endpoint, que começa com whsec_, cole-o no Brew e selecione Conectar. O Brew verifica cada entrega com a especificação Standard Webhooks (Svix).
- No Clerk, abra a aba Testing do endpoint, escolha user.created e selecione Send Example. O status no Brew muda de “Aguardando evento de teste” para “Conectado”. Um evento de exemplo só verifica o webhook: o Brew não adiciona nenhum contato nem inicia nenhuma automação.
- Ao conectar, o Brew cria gatilhos para todos os 13 eventos. Não há um botão para ativar ou desativar eventos.
- Crie uma automação, selecione o evento do Clerk dela e envie um teste enquanto ela ainda estiver como rascunho. Só automações ativas são executadas quando chega um evento correspondente.

## Eventos do Clerk compatíveis

O Brew é compatível com estes 13 tipos de evento:

- user.created
- organization.created
- organizationInvitation.created
- organizationInvitation.accepted
- organizationInvitation.revoked
- organizationMembership.created
- paymentAttempt.created
- subscription.created
- subscriptionItem.freeTrialEnding
- subscriptionItem.pastDue
- subscriptionItem.canceled
- subscriptionItem.abandoned
- waitlistEntry.created

## Sincronização de contatos e personalização

Cada evento verificado com um endereço de e-mail real cria ou atualiza um contato do Brew, identificado pelo e-mail, independentemente de alguma automação usar o evento. Quando o evento traz esses dados, o Brew preenche o nome, o sobrenome e o campo clerk_user_id.

O evento user.created também preenche clerk_username, clerk_image_url, clerk_signed_up_at e clerk_last_sign_in_at. Os eventos de convite e de participação preenchem clerk_organization_id, clerk_org_role e clerk_org_role_name. Os convites acrescentam clerk_org_invitation_status, e as participações acrescentam clerk_organization_name e clerk_organization_slug.

Os eventos de cobrança preenchem clerk_subscription_status e clerk_plan_name, e alguns acrescentam clerk_plan_slug, clerk_subscription_period_end ou clerk_is_trialing. O evento paymentAttempt.created preenche clerk_last_payment_attempt_status e clerk_last_payment_attempt_at. O waitlistEntry.created preenche clerk_waitlist_status.

Use o esquema de payload declarado do evento selecionado para as tags de mesclagem. Todos os eventos incluem email, firstName, lastName e createdAt. Os demais campos dependem do evento, como planName, planAmount, roleName, organizationName e grandTotalFormatted. Os campos planAmount e grandTotalAmount usam a menor unidade da moeda; em USD, por exemplo, 2000 equivale a US$ 20,00. Os timestamps usam o tempo Unix, em segundos.

Os IDs de objetos do Clerk, como os IDs de usuário, de organização e de assinatura, não são tags de mesclagem. O ID de usuário fica no contato, no campo clerk_user_id.

Uma conta no Clerk não estabelece consentimento para e-mails de marketing. Registre o consentimento no cadastro e confira-o antes de envios promocionais.


## O paymentAttempt.created serve para enviar um e-mail de pagamento com falha?

Não de forma confiável. O Brew recebe só o paymentAttempt.created, e não as atualizações posteriores da tentativa. O campo status dele pode ter o valor pending, paid ou failed, mas um pagamento que falha depois da criação da tentativa chega ao Brew como um evento não compatível. Para pagamentos em atraso, use o subscriptionItem.pastDue. Para mostrar um total no texto do e-mail, o campo grandTotalFormatted traz um valor já formatado, como $22.00.


## Por que um evento aparece sem que um e-mail seja enviado?

Receber um evento e enviar um e-mail são etapas separadas. Confirme que uma automação correspondente está ativa, examine os filtros e o histórico de execuções dela e verifique a elegibilidade do destinatário e o domínio de envio. Uma entrega feita com Send Example verifica o webhook, mas nunca inicia uma automação, e um evento organization.created sem um criador conhecido é registrado como não resolvido.


## Limites e solução de problemas

- O Brew não pode criar nem alterar usuários, organizações ou assinaturas do Clerk.
- Só os 13 eventos listados iniciam automações. Outros eventos do Clerk, como atualizações e exclusões de usuários, são registrados como não compatíveis.
- Se o Clerk indicar erro 401 em todas as entregas, o segredo de assinatura no Brew não corresponde ao segredo do endpoint no Clerk. Mostre o segredo atual no Clerk e conecte de novo usando esse segredo.
- O Brew exige que o segredo de assinatura comece com whsec_ e tenha pelo menos 24 caracteres.
- Revise o consentimento e a finalidade de cada e-mail. Sincronizar usuários do Clerk não autoriza envios promocionais.

## Fontes e guias de configuração

- [Guia de configuração do Clerk](https://docs.brew.new/integrations/import/clerk)
- [Crie uma automação](https://docs.brew.new/create-emails/build-an-automation)
- [Tags de mesclagem](https://docs.brew.new/create-emails/merge-tags)
- [O que você pode enviar com o Brew](https://docs.brew.new/get-started/what-you-can-send)
- [Visão geral dos webhooks do Clerk](https://clerk.com/docs/guides/development/webhooks/overview)

## Relacionados

- [Todas as integrações](https://brew.new/pt-br/browse/integrations.md)
- [Criar conta](https://brew.new/pt-br/sign-up.md)
- Site: https://brew.new