Smartling Webhooks: Technical Reference

This guide provides technical documentation for implementing, securing, and operating Smartling webhooks, covering the following concepts: 

• Subscriptions: In your subscription, you can specify which events you want to receive notifications about and where to send them.
• Events: When an event you subscribed to occurs in your Smartling project (e.g., a job is completed, an issue is created, etc.), this triggers the webhook notification.
• Delivery behavior: Smartling sends an HTTP POST request with the event details to your configured endpoint URL.
• Security: Important security information to ensure your application can receive the webhook data and process it accordingly.
• Permissions and access: Learn who has access to create and manage webhook subscriptions.

Tip: For an introduction to webhooks, please visit the Smartling Webhooks Overview.

Subscriptions

A subscription configures which events you want to receive and where to send them.
Webhook subscriptions allow you to configure the following parameters:

• subscriptionUrl: Your publicly accessible HTTPS URL that receives webhook POST requests
• events: List of event types with schema versions you want to receive
• payloadSecret (optional): Secret key used to generate HMAC signatures for request verification
• customHeaders (optional): Additional HTTP headers to include in webhook requests

Example subscription

{
 "subscriptionUid": "c0373f771ebc",
 "subscriptionName": "File Published and Source Issues Integration",
 "subscriptionUrl": "https://api.yourapp.com/webhooks/smartling",
 "events": [
   { "type": "file.published", "schemaVersion": "1.0" },
   { "type": "sourceIssue.created", "schemaVersion": "1.0" }
 ],
 "projectUids": [
   "111122233",
   "444455566"
 ]
}

Subscription limits

• There is no limit on the number of event types you can subscribe to, you can subscribe to as many different types of events as needed.  
• Your Smartling account can have a maximum of 20 subscriptions total.
• Each individual subscription can monitor up to 10 Smartling projects.

Events

Events represent significant occurrences in your Smartling account that trigger webhook notifications. 
Each webhook delivery contains a JSON payload with this example structure:

{
 "eventId": "33a05dfb-2e08-4a30-9c2b-017948fe8286",
 "eventType": "file.published",
 "schemaVersion": "1.0",
 "account": {
   "accountUid": "6fef44adc",
   "accountName": "Demo Account"
 },
 "project": {
   "projectUid": "600443364",
   "projectName": "Demo Project",
   "projectTypeCode": "BUSINESS_DOCUMENTS",
   "sourceLocale": {
     "localeId": "en",
     "description": "English [en]"
   },
   "targetLocales": [
     {
       "localeId": "fr-FR",
       "description": "French (France) [fr-FR]"
     },
     {
       "localeId": "es-ES",
       "description": "Spanish (Spain) [es-ES]"
     }
   ]
 },
 "file": {
   "fileUid": "3b88120b713a",
   "fileUri": "presentation.pptx",
   "fileType": "PPTX",
   "publishedLocale": {
     "localeId": "es-ES",
     "description": "Spanish (Spain) [es-ES]"
   },
   "createdDate": "2023-07-02T22:12:28Z",
   "lastUploadedDate": "2025-08-18T21:12:01Z",
   "publishDate": "2025-08-18T21:12:05Z",
   "namespace": "presentation.pptx",
   "callbackUrl": null,
   "directives": {
     "file_uri_as_namespace": "true"
 }
}

Key fields

The JSON payload delivered to your endpoint URL will contain the following information:

• eventId: Unique identifier for this specific event occurrence (use for deduplication)
• eventType: String identifying what happened (e.g., "translationJob.completed")
• account: Object containing the Smartling account details (e.g., "accountUid", "accountName")
• project: Object containing details about the Smartling project where the event occurred (e.g., "projectUid", "projectName")

Note: Different event types have different payload structures. The example above is for a file.published event. You can find more event types in the Events Catalog.

Delivery behavior

When a webhook notification is triggered, Smartling sends an HTTP POST request to your configured endpoint URL.

HTTP request format

When an event matches your subscription criteria, Smartling initiates delivery to your endpoint with these details:

• Method: POST
• Content-Type: application/json
• Body: JSON event payload
• Headers: Include event identification and signature verification headers
• User-Agent: Smartling-Webhooks/1.0

Delivery headers

Each webhook request includes the following standard headers for event identification and security verification:

• Event-Id: Unique identifier for the delivered event (string)
• Event-Timestamp: Unix timestamp of the current delivery attempt (integer, epoch seconds)
• Event-Signature: HMAC-SHA256 signature for request verification (space-separated list)

Example header

POST /webhooks/smartling HTTP/1.1
Host: api.yourapp.com
Content-Type: application/json
Event-Id: evt_abc123xyz
Event-Timestamp: 1705312200
Event-Signature: v1,abc123def456ghi789

Important considerations

• During secret rotation, Event-Signature may contain multiple space-separated signatures.
• Custom headers are included exactly as configured in your subscription.
• See Security for signature verification details.

Response requirements

Your endpoint must meet these criteria for successful delivery:

• Status codes: Return HTTP status code 200-299 to indicate successful processing.
• Response time: Respond within 10 seconds to avoid timeout.
• Async work: Process heavy work asynchronously (queue, worker). Return 2xx early.

Delivery attempts

Every webhook delivery is recorded as a delivery attempt with the following information:

• HTTP status code returned by your endpoint
• Response body
• Request and response timestamps

Retries and backoff

Failed deliveries are retried with deterministic exponential backoff:

• Attempts: 10 total attempts (including the initial delivery)
• Strategy: Deterministic exponential backoff
  • Base delay: 120 seconds
  • Multiplier: 2x per subsequent retry
• Maximum delivery window: 17 hours

Backoff schedule

The below schedule is an example progression of 2x backoff from a 120s base. Actual timing might slightly vary. 

If no deliveries succeed within 96 hours, the subscription is automatically disabled. You can re-enable it through the API or from the Webhook Subscriptions List in the Smartling dashboard.

Ordering

• The event delivery order is not guaranteed.
• Your handler must tolerate receiving events out of order.

Duplicates and replay protection

• Duplicate deliveries can occur (due to retries or network conditions).
• Within a context of a given subscription use the Event-Id to detect duplicates and ensure your processing is idempotent.

Manual resend

• You can request resending a specific event via the API if needed.
• Refer to Smartling's API reference site for resend endpoint details.
   

Security

Signature verification

Verify signatures using `HMAC-SHA256` over the exact raw request body. Build the string to sign as:

{Event-Id}.{Event-Timestamp}.{raw_body}

Build the signature string using the delivery headers (see Delivery behavior for header details):

• Use Event-Id and Event-Timestamp header values.
• Read the raw body from the framework without modification. Do not re-serialize JSON.
• Verify against the Event-Signature header.
• During secret rotation, multiple signatures may be present - accept if any verifies.

Secret rotation behavior

When you rotate a subscription's secret, the old secret remains valid for a 24-hour transition period. During this time:

• The Event-Signature header contains multiple space-separated signatures
• One signature is generated using the old secret, another using the new secret
• Accept the delivery if any signature verifies successfully

Rotation limits

• Maximum 10 secret rotations per subscription within any 24-hour period

Replay protection

Implement idempotency using Event-Id for replay protection (see Delivery behavior for details).

IP allowlisting

Configure your firewall/load balancer to allow webhook deliveries from these Smartling IP addresses:

• 52.200.211.6
• 52.201.54.237
• 44.194.107.158
   

Permissions & access control

Webhook subscriptions can be set up and managed in the Smartling dashboard by users with an Account Owner or Project Manager role. While Account Owners can view and manage all subscriptions, certain restrictions apply to Project Managers. See Roles and access for more information.

Similarly, two types of API tokens can be used to configure webhooks with the Smartling API: Account tokens and project-level tokens. See Smartling API token types for information on the scope and use cases for each type. 

Roles and access

Account Owner:

• Visibility: All subscriptions in the account (created by any user).
• Management: Full control of all subscriptions.

Project Manager:

• Visibility:
  • Subscriptions they personally created.
  • Subscriptions created by the Smartling API using a Project token for projects they manage.
• Management:
  • Full control of subscriptions they personally created.
  • Full control of subscriptions created by the Smartling API using a Project token for projects they manage.
• Multi-project access: If a Project Manager manages multiple projects, the above applies to each of those projects.

Smartling API token types

Account token:

When the Smartling API is called with an account token, the same account-wide visibility and management permissions apply as for an Account Owner user.

• Scope: Account-wide access
• Webhook permissions: Equivalent to Account Owner role
• Use case: Service accounts, automated systems, multi-project integrations

Project token:

When the Smartling API is called with a project token, the same visibility and management permissions apply as for a Project Manager user, but only for the token's project.

• Scope: Single project access
• Webhook permissions: Equivalent to Project Manager role for that specific project
• Use case: Project-specific integrations, team-scoped automations

Tip: For information on how to obtain and use tokens, see API Tokens.

Behavior on role and project changes

If the role or project access for a Smartling user is changed, the subscription ownership remains with the original creator. Therefore, role changes or updates to a user's permissions may impact existing webhook subscriptions.

For example:

• A project assignment is removed from the Project Manager who created the subscription:
  → The removed project is automatically removed from any affected subscription configuration.
• All project assignments are removed from the Project Manager who created the subscription:
  → All affected projects are removed from the subscription configuration. If no projects remain, the subscription is disabled.
• The role of a user who created the subscription is changed from a Project Manager role to a Translation Resource or Translation Resource Manager role:
  → The subscription is disabled.
• The Project Manager user who created the subscription is removed or deactivated:
  → The subscription is disabled.

Links to related articles

• Smartling Webhooks Overview
• Configuring Webhooks in the Smartling Dashboard
• Configuring Webhooks via the Smartling API
• Webhooks Events Catalog