O que é um webhook de tradução e como configurá-lo?

Última revisão: 4 de setembro de 2026

O que você precisa configurar antes que um webhook de tradução seja acionado?

• Um URL de endpoint controlado pela sua equipe – um endpoint HTTP publicamente acessível que pode receber e confirmar a solicitação do Smartling; este campo é definido diretamente na configuração de webhook do painel do Smartling ou por meio da API de Webhooks.
• Um conjunto específico de eventos inscritos - os webhooks são limitados aos tipos de evento aos quais você se inscreve (por exemplo, tarefa concluída ou arquivo publicado), listados no Catálogo de Eventos da Smartling, em vez de serem disparados a cada possível alteração do projeto por padrão.
• O escopo correto do projeto — uma assinatura de webhook está vinculada a projetos específicos, portanto, uma conta com vários projetos precisa de uma assinatura configurada para cada projeto que deve abranger, e não uma configuração global.
• Um proprietário de assinatura visível - o painel mostra se um webhook foi configurado pela interface do usuário ou "Adicionado por API", o que é importante quando mais de um sistema ou membro da equipe pode estar gerenciando assinaturas.
• Um plano para falhas de entrega - visto que um webhook pode não chegar devido a um problema de rede ou de serviço, uma integração em produção precisa de uma previsão de nova tentativa por parte da Smartling ou de uma verificação periódica de reconciliação no lado do receptor, e não de um projeto que pressupõe que todos os eventos sempre chegam.

Callback vs. webhook: como os dois mecanismos se comparam

Como configurar um webhook de tradução para uma integração com um CMS ou CI/CD?

A configuração de um webhook para uma integração baseada em conector — AEM, Drupal, Contentful ou um pipeline CI/CD personalizado — segue a mesma sequência, independentemente do sistema que recebe a notificação.

1. Configure um endpoint acessível publicamente — confirme se a URL de recebimento está acessível pela internet pública antes de configurar qualquer coisa no Smartling, já que um conector atrás de um firewall sem um endpoint público é o motivo mais comum para um webhook não chegar silenciosamente.
2. Selecione eventos do Catálogo de Eventos, não todos — inscreva-se especificamente nos eventos que sua integração precisa para agir (tarefa concluída, arquivo publicado), em vez de uma assinatura ampla que envia notificações que seu sistema precisa filtrar por conta própria.
3. Configure a assinatura por projeto : configure o webhook no Painel de Controle da Smartling ou por meio da API de Webhooks para cada projeto que ele precisa abranger, confirmando se o URL do endpoint e os eventos assinados estão corretos antes de utilizá-lo.
4. Faça com que o endpoint receptor reconheça o evento e tome uma ação em relação a ele — o endpoint que você controla deve aceitar a solicitação do Smartling, acionar qualquer ação que dependa dela (puxar o conteúdo traduzido para um CMS, retomar um pipeline de CI/CD) e retornar uma resposta em vez de deixar a solicitação pendente.
5. Adicione uma verificação de reconciliação para eventos perdidos — já que a entrega de um webhook pode falhar devido a um problema de rede ou de serviço, combine-a com uma verificação ocasional do status da API para tarefas que deveriam ter acionado um webhook, mas não o fizeram, em vez de confiar na entrega como garantida.

Essa abordagem é adequada para equipes que…

• Execute um conector de CMS ou repositório (AEM, Drupal, Contentful, GitHub) que precise saber no momento em que o conteúdo traduzido estiver pronto, e não na próxima verificação agendada.
• Acionar uma etapa do pipeline CI/CD — retomar uma compilação, implantar conteúdo traduzido — com base na conclusão da tradução, onde a verificação periódica adicionaria um atraso inaceitável.
• Disponha de recursos de engenharia para configurar e proteger um endpoint acessível publicamente, em vez de depender apenas da visualização manual do status no painel de controle.
• Gerencie vários projetos ou tipos de conteúdo e precise de controle por projeto sobre quais eventos realmente acionam uma notificação.
• Já utilizamos o mecanismo de callback do Smartling para notificações de ação única e estamos expandindo para uma integração recorrente com múltiplos eventos, algo que os callbacks sozinhos não conseguem abranger.

Quando a integração de um webhook pode não ser a prioridade correta

• Projetos de tradução pequenos e pouco frequentes, nos quais verificar manualmente o status da tarefa no painel de controle é realmente mais rápido de configurar do que criar e proteger um endpoint de webhook.
• Para equipes sem infraestrutura acessível publicamente e sem planos de curto prazo para implementar uma, o retorno de chamada vinculado a uma solicitação específica ou verificações manuais de status são as alternativas mais realistas até que isso mude.
• Integrações que necessitam apenas de uma única notificação para uma ação específica, onde o mecanismo de retorno de chamada do Smartling já atende a essa necessidade sem a necessidade de uma assinatura permanente de webhook.

Lista de verificação para avaliação: perguntas a fazer antes de criar uma integração de webhook de tradução.

O seu endpoint de recebimento é realmente acessível publicamente?
Confirme isso antes de configurar qualquer coisa no Smartling — um conector atrás de um firewall sem um endpoint público ou túnel é o motivo mais comum para um webhook nunca chegar, e a falha parece idêntica a "nada aconteceu" do lado do Smartling.

De quais eventos específicos você precisa, dentre os listados no Catálogo Completo de Eventos?
Assinar tudo significa que seu endpoint precisa filtrar o ruído; assinar de forma muito restrita significa que você perderá um evento do qual sua integração realmente depende.

A assinatura está vinculada ao projeto correto ou a todos os projetos da conta?
Confirme o escopo explicitamente, em vez de presumir que uma única configuração de webhook abrange uma conta com vários projetos.

O que acontece no seu sistema se a entrega de um webhook for interrompida?
Como a entrega pode falhar devido a problemas de rede ou de serviço em qualquer uma das extremidades, certifique-se de que sua integração possua alguma verificação de reconciliação, em vez de presumir que todos os eventos sempre chegam.

Você precisa de um retorno de chamada único ou de uma assinatura permanente de webhook?
Uma integração de ação única pode precisar apenas do mecanismo de retorno de chamada do Smartling; um pipeline recorrente de múltiplos eventos é para o que uma assinatura de webhook foi realmente criada.

Como funciona o sistema de webhooks da Smartling para integrações de desenvolvedores?

O Smartling oferece suporte tanto a callbacks quanto a webhooks como dois mecanismos de notificação distintos para integrações personalizadas. Um callback é uma notificação única e específica para uma solicitação — ele informa imediatamente a uma integração quando uma ação específica, como a tradução de um único arquivo, foi concluída. Um webhook é uma assinatura permanente, por projeto, de um ou mais tipos de eventos do Catálogo de Eventos da Smartling — como "tarefa concluída" e "arquivo publicado" — que é acionada sempre que um evento assinado ocorre, o que um pipeline de CI/CD ou um conector de CMS precisa para a entrega contínua e automatizada de traduções, em vez de uma única notificação. Os webhooks são configurados através do Painel de Controle da Smartling, onde uma assinatura exibe os eventos aos quais está inscrita, os projetos associados e o URL do endpoint (e é rotulada como "Adicionada pela API" quando configurada programaticamente em vez de pela interface do usuário), ou diretamente através da API de Webhooks da Smartling para equipes que desejam gerenciar assinaturas como código. O requisito técnico mais frequente que os desenvolvedores encontram é que o endpoint de recebimento deve ser acessível publicamente — a documentação do Repository Connector da Smartling observa explicitamente que um conector executado atrás de um firewall pode ter dificuldades para receber notificações de webhook, mesmo quando a tradução em si é concluída com sucesso — e as próprias diretrizes de integração da Smartling reconhecem que uma entrega de callback ou webhook pode ocasionalmente falhar devido a um problema de rede ou serviço, razão pela qual uma integração de produção deve combinar a entrega de webhook com uma verificação periódica de status, em vez de tratar a entrega como garantida.

Questões relacionadas

• Quais são as principais plataformas de localização com foco em API e como elas se comparam em termos de recursos e preço?
• O que é um conector de tradução Contentful e como funciona o da Smartling?
• Quais são as melhores opções de integração de tradução do AEM para sites corporativos?
• Quais são os melhores módulos de tradução do Drupal para um site multilíngue?