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? This guide is for the Account Admin who needs to create webhooks, and the developer who builds the receiving endpoint, within the wxrks platform.
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
POSTrequest to your Webhook URL with a JSON body.Your endpoint must answer with any HTTP 2xx status within 3 seconds. Any other answer is recorded as a failed delivery.
When a delivery fails because your endpoint is unavailable or busy, wxrks retries it automatically. You can also retry any failed delivery from the delivery log (see Delivery log and retries).
Create a webhook
Only an Account Admin can create and manage webhooks.
Go to Settings > Account Settings > Webhooks and stay on the Webhooks tab.
Enter the Webhook URL. It must start with
https://; Save stays disabled forhttp://addresses.Optionally enter a Secret. wxrks sends it with every request so your endpoint can check where the request came from (see Verify that a request came from wxrks).
Pick one Event.
Click Save and confirm the dialog Do you want to save this webhook to <url>?
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 Active only if your endpoint answers with an HTTP 2xx status to one of them.
⚠️ Warning: If the test fails, wxrks does not show an error. The webhook just stays Inactive. After saving, check the Status switch of the new row, 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 the Webhooks page displays for wxrks requests (34.230.169.172 at the time of writing).
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 (uuid, event, URL, creation date and status) without the secret, so keep your own copy of the secret when you create the webhook. See Authenticating with the wxrks API and the wxrks API documentation.
Events you can subscribe to
Every payload carries an event_type field with the event name. Each event name below links to an example payload in the wxrks API documentation.
Projects
NEW_PROJECT: a project was created.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 payload includesprevious_statusandnew_status.PROJECT_INGESTION_COMPLETED: wxrks finished reading the project's files. The payload containsproject_uuid,project_nameandorg_unit_uuid, plusworkflows,target_localesand, when the project has one,ci_tag.PROJECT_TRANSLATION_FINISHED: pre-translation finished. The payload includestotal_work_units,total_work_units_completedandtotal_work_units_failed.
Tasks
TASK_ASSIGNED: a task was assigned to someone.TASK_STATUS_CHANGE: a task's status changed (previous_statusandnew_status).TASK_UPDATE: a task was edited.
Work units
WORK_UNIT_STATUS_CHANGE: a work unit's status changed (previous_statusandnew_status), with languages, file name, word and character counts, and whether it is the last workflow step.WORK_UNIT_TRANSLATION_FILE_READY: the translated file is ready. The payload includestranslated_file_urlandoriginal_file_url, which are temporary download links that stay valid for about 7 days.
Organizations, Organizational Units and users
NEW_ORG: an Organization was created.ORG_UPDATE: an Organization was edited.NEW_ORG_UNIT: an Organizational Unit was created.ORG_UNIT_UPDATE: an Organizational Unit was edited.NEW_USER: a user was created.USER_UPDATE: a user was edited.
Project, task and work unit payloads include the uuid of the project and the Organizational Unit, so you can match them to your own records.
Verify that a request came from wxrks
Every request carries these headers:
X-BWX-Event-ID: a unique ID for this event, kept on every retry. Use it to ignore duplicates.X-BWX-Webhook-ID: the ID of the webhook that sent it.X-BWX-Webhook-Secret: the Secret you saved, exactly as you typed it, or an empty value if you left it blank.User-Agent: wxrks
Compare X-BWX-Webhook-Secret with the secret you stored, and reject the request if they differ:
if header "X-BWX-Webhook-Secret" != YOUR_SECRET: answer 401 and stop
if "X-BWX-Event-ID" was already processed: answer 200 and stop
answer 200, then process the event
ℹ️ Note: wxrks does not sign the request body, and does not send a timestamp, so a receiver cannot detect a replayed request. Keep the secret private, use a long random value, and accept requests only over HTTPS.
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: after 10 seconds, 1 minute and 2 minutes. Each automatic retry keeps the sameX-BWX-Event-ID. Other answers, such as400or401, are not retried automatically.No ordering guarantee. Events can arrive out of order, so use fields such as
new_statusrather than 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.No automatic disabling. A webhook stays Active however many deliveries fail, so check the delivery log regularly.
Delivery log and retries
Open the Events tab on the Webhooks page. It lists every delivery attempt. Filter by webhook, event or result, and open Details to see what was sent and how your endpoint answered.
To send a failed event again yourself, click Retry on its row. A manual retry keeps the original X-BWX-Event-ID and adds an X-BWX-Retry-Of header with the ID of the original attempt. The test requests used when a webhook is created have no Retry button.
Through the API, GET /api/v3/webhook/events returns the same log (50 entries per page by default, up to 500), and POST /api/v3/webhook/events/{id}/retry retries one entry.
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, work unit (including WORK_UNIT_TRANSLATION_FILE_READY) and Organizational Unit events for that unit are not sent. Organization and user events are not affected by it. See All about Organizational Units.
Webhooks or Pipelines?
A webhook sends the event's JSON as it is, with the three X-BWX headers, a delivery log, and automatic and manual retry. A Pipeline with an http action is a request you write yourself: you choose the URL, method (POST, PUT, DELETE or GET), headers and body, insert values from the event into them, and use Secrets for credentials. A Pipeline can react to more events than the 17 above, but it has no delivery log, no timeout setting and no retry, and a 4xx or 5xx answer does not fail the job. 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 for the syntax.
Troubleshooting
The webhook stays Inactive after saving. Your endpoint did not answer with an HTTP 2xx status to the test request within 3 seconds, or it is not reachable from the internet. Fix the endpoint and turn the Status switch on.
No events arrive. Check that the webhook is Active, that it is subscribed to the event you expect (each webhook has one), and that Enable Webhook Events is on for the Organizational Unit.
The Events tab 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 do the processing afterwards.
I received the same event twice. Ignore the second delivery by checking
X-BWX-Event-ID. Automatic and manual retries keep the same ID. A manual retry from the Events tab also carriesX-BWX-Retry-Of, so you can recognize it.
Quick reference
Item | Value |
Where | Settings > Account Settings > Webhooks |
Who can manage | Account Admin |
URL | HTTPS only |
Events per webhook | One |
Success | Any HTTP 2xx within 3 seconds |
Retries | Automatic, up to 3 times (after 10 s, 1 min and 2 min) on 5xx, 408, 429 or no connection; manual from the Events tab or the API |
Verification |
|
De-duplication |
|