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 HTTP 200 within 3 seconds. Any other answer is recorded as a failed delivery.
wxrks does not retry a failed delivery on its own. You retry it 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 HTTP 200 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. 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.
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_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 or 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. For a full example of each payload, see the wxrks API documentation.
Verify that a request came from wxrks
Every request carries these headers:
X-BWX-Event-ID: a unique ID for this delivery. 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: BureauWorks
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
process the event, then answer 200
ℹ️ 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 HTTP 200 only. A
201or204answer is recorded as failed.Timeout is 3 seconds. Answer first and do the heavy work afterwards.
No automatic retries. A failed event is not sent again until you retry it.
No ordering guarantee. Events can arrive out of order, so use fields such as
new_statusrather than the arrival order.Duplicates are possible. 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, click Retry on its row. A retry is a new delivery: it carries a new X-BWX-Event-ID and an extra 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 and Organizational Unit events for that unit are not sent. Organization and user events, and WORK_UNIT_TRANSLATION_FILE_READY, 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 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 HTTP 200 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 with something other than HTTP 200, such as
201or204. Answer200.I received the same event twice. Ignore the second delivery by checking
X-BWX-Event-ID. A retry from the Events tab has a different ID; compareX-BWX-Retry-Ofto recognize it.
Quick reference
Item | Value |
Where | Settings > Account Settings > Webhooks |
Who can manage | Account Admin |
URL | HTTPS only |
Events per webhook | One |
Success | HTTP 200 within 3 seconds |
Retries | Manual only, from the Events tab or the API |
Verification |
|
De-duplication |
|