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
Go to Settings > Automation > Webhooks and click Create webhook.
In the New webhook window, enter the Endpoint URL. It must start with
https://.Pick one Event.
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.
Click Create webhook.
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 includesprevious_statusandnew_status.PROJECT_INGESTION_COMPLETED: wxrks finished reading the project's files, or failed to.PROJECT_TRANSLATION_FINISHED: pre-translation finished. The body includestotal_work_units,total_work_units_completedandtotal_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 indetails.logfileto read them.
Tasks
TASK_ASSIGNED: a task was assigned.TASK_STATUS_CHANGE: a task's status changed (previous_statusandnew_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 includesprevious_due_dateandnew_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 fieldresponseisACCEPTEDorDECLINED.
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_statusandnew_status).WORK_UNIT_TRANSLATION_FILE_READY: wxrks generated a translated file, or tried to and failed. Checktranslation_statusfirst:TRANSLATED: the file is ready.translated_file_urlandoriginal_file_urlare 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 includeserror_codeanderror_message. For example,BWX-006means 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.statusisIMPORTEDorERROR; on an error,errorsays 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_typesays which, andstatussays how it ended (COMPLETEDorFAILED, for example). The body has no download link: call the API request named indetails.jobto get it.
Organizations, Organizational Units and users
NEW_ORGandORG_UPDATE: an Organization was created or edited.NEW_ORG_UNITandORG_UNIT_UPDATE: an Organizational Unit was created or edited.NEW_USERandUSER_UPDATE: a user was created (from the app, single sign-on or SCIM provisioning) or edited.
ℹ️ 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 |
|---|---|
| A unique ID for the event, the same on every retry. Use it to ignore duplicates. |
| The event name, such as |
| The ID of the webhook that sent it. |
| When the request was signed, in Unix seconds. Only when the webhook has a Signing secret. |
|
|
| Only on an event sent again by hand: the ID of the original delivery. |
| Your Signing secret in plain text. Kept for older receivers: check |
| Always |
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,201or204.Timeout is 3 seconds. Answer first and do the heavy work afterwards.
Automatic retries. If your endpoint answers
5xx,408or429, 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 as400or401(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-IDto 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.
To send an event again once your endpoint is fixed:
Open the row's More actions menu (⋯) and click Send again.
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,408or429, 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:
ℹ️ Note: Deleting a webhook also deletes its dead letters.
Through the API
GET /api/v3/webhook/eventsreturns the same log (50 entries per page by default, up to 500). AdddeadLetter=trueto list only dead letters. Each entry haseventId, the same on every attempt of an event, and dead letters also havedeadAt, the time wxrks gave up.POST /api/v3/webhook/events/{uuid}/retrysends 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.
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 |
Dead letter | After the last retry fails, on any other |
Send again | Send again in the Events section, or |
Turned off by wxrks | 10 events in a row not delivered, over at least 3 days |
Verification |
|
De-duplication |
|
Related articles




