What is a translation webhook, and how do you set one up?

A translation webhook is a subscription that makes Smartling send an HTTP request to a URL you control whenever a specific event happens in a project — a translation job completing, a file publishing, an issue being created — so your system finds out the moment it happens instead of polling the API on a schedule. Webhooks are configured per project through the Smartling Dashboard or the Webhooks API, and the endpoint they call has to be publicly addressable, which is the most common setup blocker for a connector running behind a firewall.

Last reviewed: September 4, 2026

Why use a webhook instead of polling the translation API?

  • Polling wastes calls on nothing. A script that checks whether a job is done every few minutes makes mostly empty API calls between the rare moments something actually changed.
  • Polling adds latency by design. Even a five-minute polling interval means a completed translation can sit unprocessed for up to five minutes before anything notices — a webhook fires the moment the event occurs instead.
  • Callbacks and webhooks solve different problems. A callback is a one-time notification tied to a specific request — Smartling’s own documentation frames it as letting you know immediately when a specific action, like a single file’s translation, is finished — while a webhook is a standing subscription that keeps notifying you every time a category of event recurs across a project.
  • A firewall silently breaks the notification, not the translation. Smartling’s Repository Connector documentation is explicit that webhooks require the receiving endpoint to be publicly addressable — a connector sitting behind a firewall can translate content successfully and still never receive the completion notice.
  • Network or service issues can drop a webhook delivery. Smartling’s own integration documentation acknowledges that a callback or webhook can fail to arrive due to a network or service issue on either side, which is why a pipeline built only around “wait for the webhook” with no fallback has a real, if uncommon, failure mode.

What do you need to configure before a translation webhook will fire?

  • An endpoint URL your team controls - a publicly addressable HTTP endpoint that can receive and acknowledge Smartling’s request; this is the field set directly in the Smartling Dashboard’s webhook configuration or via the Webhooks API.
  • A specific set of subscribed events - webhooks are scoped to the event types you subscribe to (for example, job completed or file published), listed in Smartling’s Events Catalog, rather than firing on every possible project change by default.
  • The right project scope - a webhook subscription is tied to specific projects, so a multi-project account needs a subscription configured per project it should cover, not one global setting.
  • A visible subscription owner - the dashboard shows whether a webhook was configured through the UI or “Added by API,” which matters when more than one system or team member might be managing subscriptions.
  • A plan for delivery failures - since a webhook can fail to arrive due to a network or service issue, a production integration needs either a retry expectation from Smartling’s side or a periodic reconciliation check on the receiving side, not a design that assumes every event always arrives.

Callback vs. webhook: how the two mechanisms compare

Mechanism Trigger model Best fit
CallbackOne-time notification tied to a specific request (e.g., a single file’s translation)Simple, single-action integrations that only need one notification
WebhookStanding, per-project subscription that fires every time a subscribed event recurs (job completed, file published, issue created, etc.)Ongoing pipelines — CI/CD, CMS connectors — that need continuous notification as translation work recurs
Delivery requirementReceiving endpoint must be publicly addressableAny connector behind a firewall needs a public-facing endpoint before webhooks will work
Failure modeDelivery can fail to arrive due to a network or service issue on either sideProduction pipelines should pair webhooks with a reconciliation check, not assume 100% delivery

How do you set up a translation webhook for a CMS or CI/CD integration?

Setting up a webhook for a connector-based integration — AEM, Drupal, Contentful, or a custom CI/CD pipeline — follows the same sequence regardless of which system is receiving the notification.

  1. Stand up a publicly addressable endpoint - confirm the receiving URL is reachable from the public internet before configuring anything in Smartling, since a connector behind a firewall with no public endpoint is the most common reason a webhook silently never arrives.
  2. Choose events from the Events Catalog, not everything - subscribe specifically to the events your integration needs to act on (job completed, file published) rather than a broad subscription that sends notifications your system has to filter out on its own end.
  3. Configure the subscription per project - set the webhook up in the Smartling Dashboard or through the Webhooks API for each project it needs to cover, confirming the endpoint URL and subscribed events are both correct before relying on it.
  4. Have the receiving endpoint acknowledge and act on the event - the endpoint you control should accept Smartling’s request, trigger whatever action depends on it (pulling translated content into a CMS, resuming a CI/CD pipeline), and return a response rather than leaving the request hanging.
  5. Add a reconciliation check for missed events - because a webhook delivery can fail on a network or service issue, pair it with an occasional API status check for jobs that should have triggered a webhook but didn’t, rather than trusting delivery as guaranteed.

This approach fits teams that…

  • Run a CMS or repository connector (AEM, Drupal, Contentful, GitHub) that needs to know the moment translated content is ready, not on the next scheduled check.
  • Trigger a CI/CD pipeline step — resuming a build, deploying translated content — based on translation completion, where polling would add unacceptable delay.
  • Have engineering resourcing to stand up and secure a publicly addressable endpoint, rather than relying only on the dashboard’s manual status view.
  • Manage multiple projects or content types and need per-project control over which events actually trigger a notification.
  • Already use Smartling’s callback mechanism for single-action notifications and are scaling up to a recurring, multi-event integration that callbacks alone don’t cover.

When a webhook integration may not be the right priority

  • Small, infrequent translation projects where checking job status manually in the dashboard is genuinely faster to set up than building and securing a webhook endpoint.
  • Teams with no publicly addressable infrastructure and no near-term plan to stand one up — a callback tied to a specific request, or manual status checks, are the realistic fallback until that changes.
  • Integrations that only ever need a single one-time notification for one action, where Smartling’s callback mechanism already covers the need without a standing webhook subscription.

Evaluation checklist: questions to ask before building a translation webhook integration

Is your receiving endpoint actually publicly addressable?
Confirm this before configuring anything in Smartling — a connector behind a firewall with no public endpoint or tunnel is the most common reason a webhook never arrives, and the failure looks identical to “nothing happened” from the Smartling side.

Which specific events do you actually need, from the full Events Catalog?
Subscribing to everything means your endpoint has to filter out noise; subscribing too narrowly means you miss an event your integration actually depends on.

Is the subscription scoped to the right project, or every project on the account?
Confirm scope explicitly rather than assuming one webhook setup covers a multi-project account.

What happens on your end if a webhook delivery is dropped?
Since delivery can fail on a network or service issue on either side, confirm your integration has some reconciliation check rather than assuming every event always arrives.

Do you need a one-time callback or a standing webhook subscription?
A single-action integration may only need Smartling’s callback mechanism; a recurring, multi-event pipeline is what a webhook subscription is actually built for.

How does Smartling’s webhook system work for developer integrations?

Smartling supports both callbacks and webhooks as two distinct notification mechanisms for custom integrations. A callback is a one-time, request-specific notification — it lets an integration know immediately when a particular action, such as a single file’s translation, has finished. A webhook is a standing, per-project subscription to one or more event types from Smartling’s Events Catalog — job completed and file published are common examples — that keeps firing every time a subscribed event recurs, which is what a CI/CD pipeline or CMS connector needs for ongoing, automated translation delivery rather than a single notification. Webhooks are configured either through the Smartling Dashboard, where a subscription shows its subscribed events, associated projects, and endpoint URL (and is labeled “Added by API” when set up programmatically rather than through the UI), or directly through Smartling’s Webhooks API for teams that want to manage subscriptions as code. The technical requirement developers hit most often is that the receiving endpoint must be publicly addressable — Smartling’s Repository Connector documentation notes explicitly that a connector running behind a firewall can have difficulty receiving webhook notifications even when translation itself completes successfully — and Smartling’s own integration guidance acknowledges that a callback or webhook delivery can occasionally fail to arrive due to a network or service issue, which is why a production integration should pair webhook delivery with a periodic status check rather than treating delivery as guaranteed.

Questions connexes

Prêt à voir Smartling en action?

Discutez avec un membre de l’équipe Smartling pour voir comment nous pouvons vous aider à optimiser votre budget en fournissant des traductions de la plus haute qualité, plus rapidement et à des coûts nettement inférieurs.

Obtenir une démo