Skip to main content

Webhooks: event notifications

Create a webhook, choose an event, verify requests from wxrks, and understand delivery, the delivery log and retries.

A webhook makes wxrks send an HTTPS request to your system when something happens, such as a project being created, a task being assigned or a translated file becoming ready. Use webhooks instead of repeatedly calling the API to ask whether anything changed.

💡 Who is this for? The Account Admin who creates and monitors webhooks, and the developer who builds the endpoint that receives them. Only an Account Admin can create and manage webhooks.

Table of contents

How webhooks work

Each webhook watches one event. To be notified about several events, create one webhook per event.

When the event happens, wxrks sends a POST request with a JSON body to your Endpoint URL. Your endpoint must answer with any HTTP 2xx status within 3 seconds. Any other answer is a failed delivery.

When a delivery fails because your endpoint is unavailable or busy, wxrks tries again on its own. If it still fails, wxrks stops trying and keeps the event as a dead letter, which you can send again once your endpoint is fixed (see Delivery log and dead letters).

Create a webhook

  1. Go to Settings > Automation > Webhooks and click Create webhook.

  2. In the New webhook window, enter the Endpoint URL. It must start with https://.

  3. Pick one Event.

  4. Optionally enter a Signing secret. wxrks uses it to sign every request so your endpoint can check that the request came from wxrks (see Verify that a request came from wxrks). wxrks stores it encrypted and never shows it again, so keep your own copy.

  5. Click Create webhook.

The New webhook window opened from Settings, Automation, Webhooks, with red boxes and step badges 2 to 5 around the Endpoint URL, Event and Signing secret fields and the Create webhook button

The webhook starts inactive

A new webhook is created inactive. wxrks then sends up to 3 test requests (event WEBHOOK_VALIDATION), one second apart, and turns the webhook on only if your endpoint answers one of them with an HTTP 2xx status.

⚠️ Warning: If the test fails, the webhook just stays off. After creating it, check its switch in the Active column of the webhook list, fix your endpoint, and turn the switch on. Only active webhooks receive events.

💡 Tip: If your firewall filters incoming traffic, allow the IP address that How webhooks work shows under Source address (34.230.169.172 at the time of writing). Every request comes from it.

Create a webhook with the API

Send POST /api/v3/webhook with the fields url, type (the event name) and, optionally, secret. The same activation test applies. The response returns the new webhook without the secret. See Authenticating with the wxrks API and the wxrks API documentation.

Events you can subscribe to

Every request body carries an event_type field with the event name. In the Event list, events appear under a readable name, such as Task Overdue for TASK_OVERDUE. Each event name below links to its body, with every field and an example, on the Webhook payloads page of the API documentation.

Projects

  • NEW_PROJECT: a project with files was created, from the app, the API, continuous localization or work unit automation.

  • NEW_EMPTY_PROJECT: a project without files was created.

  • PROJECT_UPDATE: the project's information was edited.

  • PROJECT_STATUS_CHANGE: the project's status changed. The body includes previous_status and new_status.

  • PROJECT_INGESTION_COMPLETED: wxrks finished reading the project's files, or failed to.

  • PROJECT_TRANSLATION_FINISHED: pre-translation finished. The body includes total_work_units, total_work_units_completed and total_work_units_failed.

  • PROJECT_LOGFILE_COMPLETED: a logfile (the word count analysis of a project) finished, whether someone created it in the app or through the API, or wxrks ran it to calculate costs. The body has no word counts: call the API request named in details.logfile to read them.

Tasks

  • TASK_ASSIGNED: a task was assigned.

  • TASK_STATUS_CHANGE: a task's status changed (previous_status and new_status).

  • TASK_UPDATE: a task was edited.

  • TASK_DUE_DATE_CHANGE: a task's due date was changed or removed, on the task or in a bulk task update. The body includes previous_due_date and new_due_date, in milliseconds; each has no value when there was no due date or it was removed. Saving the same due date again sends nothing, and neither does the due date given when the tasks are created.

  • TASK_OVERDUE: a task that is Assigned, Pending Acceptance or Pending Confirmation passed its due date. wxrks checks every 5 minutes, so the event can arrive up to 5 minutes late. It is sent once per due date, and a due date set more than 24 hours in the past is not reported.

  • TASK_VENDOR_RESPONSE: the vendor accepted or rejected a task offered to them (see Requiring Vendors to Accept or Reject Assigned Tasks). The field response is ACCEPTED or DECLINED.

Segment comments

  • SEGMENT_COMMENT_CREATED: someone added a comment or a reply to a segment, in the Editor or through the API. The body carries IDs only, not the comment's text: to read it, call List Work Unit Comments. Private comments, project messages and comments imported from a bilingual file send nothing.

Work units

A work unit is one file in one target language at one workflow step.

  • WORK_UNIT_CREATED: a work unit's file was read and the work unit is ready, once per workflow step. The body includes the file name, the languages, the workflow step and the word, character and segment counts. A work unit whose creation failed sends nothing.

  • WORK_UNIT_STATUS_CHANGE: a work unit's status changed (previous_status and new_status).

  • WORK_UNIT_TRANSLATION_FILE_READY: wxrks generated a translated file, or tried to and failed. Check translation_status first:

    • TRANSLATED: the file is ready. translated_file_url and original_file_url are temporary download links, valid for about 7 days.

    • ERROR: the file can't be generated, and there is no download link. When the failure has a wxrks error code, the body also includes error_code and error_message. For example, BWX-006 means the translation has characters the file's encoding can't hold (see When a translation has characters the encoding can't hold (BWX-006)).

  • WORK_UNIT_IMPORT_FINISHED: an import of a bilingual file (XLIFF, XLSX or DOCX) into a work unit ended. status is IMPORTED or ERROR; on an error, error says why. The body also counts the segments in the file and the segments the import updated, confirmed or left untouched.

  • TRANSLATION_KIT_JOB_FINISHED: a file job ended, such as a bilingual export, a download of translated or source files, or a bulk import. translation_kit_type says which, and status says how it ended (COMPLETED or FAILED, for example). The body has no download link: call the API request named in details.job to get it.

Organizations, Organizational Units and users

ℹ️ Note: WORK_UNIT_TRANSLATION_FILE_READY is sent when wxrks generates a translated file for a download from the Editor or through the API. Download Translated Files on the project page does not send it.

Project, task and work unit events include the uuid of the project and of the Organizational Unit, so you can match them to your own records.

Verify that a request came from wxrks

Every request carries these headers (see Every request):

Header

What it holds

X-BWX-Event-ID

A unique ID for the event, the same on every retry. Use it to ignore duplicates.

X-BWX-Event-Type

The event name, such as TASK_ASSIGNED, or WEBHOOK_VALIDATION for the test requests.

X-BWX-Webhook-ID

The ID of the webhook that sent it.

X-BWX-Timestamp

When the request was signed, in Unix seconds. Only when the webhook has a Signing secret.

X-BWX-Signature

v1= followed by the lowercase hexadecimal HMAC-SHA256 of {X-BWX-Timestamp}.{raw body}, keyed with your Signing secret. Only when the webhook has one.

X-BWX-Retry-Of

Only on an event sent again by hand: the ID of the original delivery.

X-BWX-Webhook-Secret

Your Signing secret in plain text. Kept for older receivers: check X-BWX-Signature instead.

User-Agent

Always wxrks.

Check the signature, and reject a request whose timestamp is more than 5 minutes away from your clock. This protects you against altered and replayed requests:

expected = "v1=" + hex(HMAC_SHA256(key = YOUR_SECRET, message = X-BWX-Timestamp + "." + raw body))
if X-BWX-Signature != expected: answer 401 and stop
if X-BWX-Timestamp is more than 5 minutes from now: answer 401 and stop
if X-BWX-Event-ID was already processed: answer 200 and stop
answer 200, then process the event

Every attempt is signed again with a new timestamp, retries included. See Verifying the signature for example code. Keep the secret private and use a long random value.

Delivery behavior

  • Success means any HTTP 2xx status, such as 200, 201 or 204.

  • Timeout is 3 seconds. Answer first and do the heavy work afterwards.

  • Automatic retries. If your endpoint answers 5xx, 408 or 429, or can't be reached, wxrks sends the event again up to 3 times: about 10 seconds, 1 minute and 2 minutes later. Pending retries are kept, so a retry is not lost when wxrks restarts or deploys a new version.

  • Dead letters. wxrks stops trying and marks the event as a dead letter when:

    • the third automatic retry fails too;

    • your endpoint answers any other 4xx, such as 400 or 401 (these are not retried: the event becomes a dead letter at once);

    • the webhook was turned off by the time of a retry.

  • No ordering guarantee. Events can arrive out of order, so rely on fields such as new_status, not on the arrival order.

  • Duplicates are possible, for example when your endpoint processed an event but answered too late and wxrks retried it. Use X-BWX-Event-ID to ignore a delivery you already processed.

Delivery log and dead letters

The Events section, below the webhook list on the Webhooks page, lists every delivery attempt, newest first, with the status your endpoint answered. Filter it by Webhook, Event or Result. To see what was sent and how your endpoint answered, open a row's More actions menu (⋯) and click Details.

An attempt marked Dead letter is the last one for an event that wxrks gave up delivering. To list only those, set Result to Dead letters.

The Events section of the Webhooks page with the Result filter set to Dead letters, red boxes around that filter, the Dead letter badge next to Failed (400) on a row, and Send again in the row's open More actions menu

To send an event again once your endpoint is fixed:

  1. Open the row's More actions menu (⋯) and click Send again.

  2. Confirm Send this event to the endpoint again?

The new attempt keeps the original X-BWX-Event-ID and adds an X-BWX-Retry-Of header with the ID of the attempt you sent again. In the log it is a new row with its own ID and the same event ID.

  • If your endpoint answers with a 2xx status, the event is delivered and is no longer a dead letter.

  • If your endpoint answers 5xx, 408 or 429, or can't be reached, the event gets the same automatic retries as a new one. If they all fail, the last attempt becomes the dead letter.

The test requests sent when a webhook is created can't be sent again.

The Details window of a dead letter says when wxrks stopped trying:

The Details window of a dead letter, with a red box around the line "wxrks stopped trying to deliver this event on Nov 19, 2026, 5:42 PM. Send it again once your endpoint is fixed.", above the endpoint URL, the response and the payload

ℹ️ Note: Deleting a webhook also deletes its dead letters.

Through the API

  • GET /api/v3/webhook/events returns the same log (50 entries per page by default, up to 500). Add deadLetter=true to list only dead letters. Each entry has eventId, the same on every attempt of an event, and dead letters also have deadAt, the time wxrks gave up.

  • POST /api/v3/webhook/events/{uuid}/retry sends one entry again, exactly like Send again.

When wxrks turns a webhook off

When an endpoint keeps failing for days, wxrks turns its webhook off instead of sending to it forever. This happens when 10 events in a row are not delivered after their retries, and the first of them failed at least 3 days earlier. Then:

  • the Account Admins receive one email about it;

  • the webhook list shows Turned off by wxrks on [date]: deliveries kept failing under the webhook's switch;

  • the 10 failed events are in the dead letters.

Only failures of your endpoint count: an answer outside the 2xx range, no answer, or a rejected certificate. Events you send again by hand don't count.

To turn the webhook back on, fix your endpoint and turn its switch on. wxrks tests the endpoint again first, as when you created it. Then send the dead letters again if your system needs them.

⚠️ Warning: Events that happen while a webhook is off are not sent and not kept, so they never become dead letters. To catch up, read the current state of your records through the API.

Choose which Organizational Units send events

Each Organizational Unit has an Enable Webhook Events switch on its Notifications tab, on by default. When it is off, project, task, segment comment, work unit and Organizational Unit events of that unit are not sent. Organization and user events are not affected. See All about Organizational Units.

The Notifications tab of an Organizational Unit page, with a red box around the Enable Webhook Events switch

Webhooks or Pipelines?

A webhook sends the event's JSON as it is, with its X-BWX headers, automatic retries, a delivery log and dead letters. A Pipeline with an http action is a request you write yourself: you choose the URL, method, headers and body, insert values from the event, and keep credentials in Secrets. A Pipeline reacts to more events than the ones above, but it does not retry on its own: a failed request shows in the Pipeline's run history, where you retry the run yourself. Use a webhook to tell another system that something happened, and a Pipeline to call a specific API with a custom request. See Getting Started with Pipelines in wxrks.

Troubleshooting

The webhook stays off after I create it. Your endpoint did not answer a test request with an HTTP 2xx status within 3 seconds, or it is not reachable from the internet. Fix the endpoint and turn the switch on.

The webhook was turned off and I didn't do it. Its endpoint failed 10 events in a row over at least 3 days, and wxrks turned it off (see When wxrks turns a webhook off). Fix the endpoint, turn the switch on, and send the dead letters again.

No events arrive. Check that the webhook is on, that it watches the event you expect (each webhook has one), and that Enable Webhook Events is on for the Organizational Unit.

The Events section shows failed deliveries, but my system received them. Your endpoint answered after 3 seconds, or with a status outside the 2xx range. Answer right away with a 2xx status and process the event afterwards.

An event became a dead letter without any retry. Your endpoint answered with a 4xx status other than 408 or 429, such as 401 for a wrong secret check. wxrks does not retry those. Fix the endpoint and click Send again.

I received the same event twice. Ignore the second delivery by checking X-BWX-Event-ID: automatic retries and Send again keep the same ID. An event sent again by hand also carries X-BWX-Retry-Of.

WORK_UNIT_TRANSLATION_FILE_READY arrives with translation_status ERROR. wxrks could not generate the translated file, so there is no download link. If error_code is BWX-006, fix the segments whose characters the file's encoding can't hold, or change the file's encoding, and download the file again.

No TASK_OVERDUE for a late task. The event is sent only for tasks that are Assigned, Pending Acceptance or Pending Confirmation, up to 5 minutes after the due date, and once per due date. A due date set more than 24 hours in the past is not reported.

Quick reference

Item

Value

Where

Settings > Automation > Webhooks

Who can manage

Account Admin

URL

HTTPS only

Events per webhook

One

Success

Any HTTP 2xx within 3 seconds

Automatic retries

Up to 3 (about 10 s, 1 min and 2 min later) on 5xx, 408, 429 or no connection

Dead letter

After the last retry fails, on any other 4xx, or when the webhook is off at retry time

Send again

Send again in the Events section, or POST /api/v3/webhook/events/{uuid}/retry

Turned off by wxrks

10 events in a row not delivered, over at least 3 days

Verification

X-BWX-Signature (HMAC-SHA256 of the timestamp and the body, keyed with your secret)

De-duplication

X-BWX-Event-ID

Related articles

Did this answer your question?