Consume the Workflow Run failed webhook to know when a workflow didn't complete successfully. While you can observe Workflow Runs for any outcome and a full run timeline for every workflow that has been started, it is important to also know when a workflow failed.
Even if you already listen to the Payment status updates webhooks, consuming this additional webhook is strongly encouraged if you use Capture or Cancel via Workflows, as a failure to capture or cancel will neither fail the payment itself nor lead to an update of the payment status. Not knowing that a capture or cancel failed could therefore result in unintended consequences.
Webhook setup
As with any Webhook setup, head to the "Developers" section in the dashboard to configure a webhook. Once the webhook is active, your endpoint will be notified the next time a Workflow Run fails. When Webhook signing is enabled in the dashboard, the Workflow Run failed webhooks will also contain the signature header.
Webhook payload
Version 1.0 of the webhook payload consists of the below fields. New fields could be added and are not considered breaking changes.
| Payload field | Description |
|---|---|
| eventType | WORKFLOW_RUN.FAILED for failed runs. We might support additional types in the future. |
| version | Webhook version for this eventType. |
| date | Date and time when the webhook event was sent. |
| primerAccountId | Primer Account ID of the account that belongs to the failed run. |
| triggerEventId | An optional ID passed with the trigger to identify the origin of the event that started the workflow. For payments created, this would be the payment ID, but other triggers might not set an event ID and the value returned with the webhook will then be null. |
| workflow / id | The ID of the workflow that had a failed run. |
| workflow / name | The name of the workflow that had a failed run. |
| workflow / version | The version of the workflow that had a failed run. |
| run / timestamp | Date and time when the workflow run failed. |
| run / id | The ID of the workflow run that failed. This can be used to easier access the workflow run in the dashboard. |
| run / status | The Workflow Run status will always be FAILED currently. In the future, COMPLETED might become an additional option for Workflow Run Webhooks. |
| lastError / aplicationId | The application used for the block that lead to the workflow run failure. The values here are dependent on the applications used within workflows, but could for example be SLACK, ONFIDO, PRIMER_PAYMENTS, etc. |
| lastError / actionId | The ID of the action used for the block that lead to the workflow run failure. The values here are dependent on the actions used within workflows, but could for example be send_message, capture_payment, create_ticket, etc. |
| lastError / diagnosticsId | A diagnostics ID helping Primer to debug traces when needed (optional). |
| lastError / message | The error message as also displayed in the Workflow Run Timeline (optional). |
Example for a payment workflow
The payload for a payment workflow will not contain any payment data, only the Payment ID in a field called triggerEventId, as the trigger event ID for a payment workflow is the Payment ID. Use the Payments API to get the latest status and payment data for the payment linked to this ID.
The below example represents a failed Workflow Run using the "Payment created" trigger from the Payments app:
1234567891011121314151617181920212223
{ "eventType": "WORKFLOW_RUN.FAILED", "version": "1.0", "date": "2024-02-21 15:36:16.167687", "primerAccountId": "123abcde-99f2-416e-8013-6ecd1c1285c3", "triggerEventId": "DdRZ6YY0", "workflow": { "id": "ecb8d3bc-123a-4d56-826e-ef8d4cc3d2a2", "name": "MIT UK Card", "version" : 8 }, "run": { "timestamp": "2024-03-07T12:20:14.394429", "id": "bbb1c3cc-805d-4d97-826e-ef8d4cc3d2a2", "status": "FAILED", "lastError": { "applicationId": "RISKIFIED", "actionId": "checkout_denied", "diagnosticsId": "1234567890", "message": "Order already decided" } }}
Example for any other workflow
The below example represents a failed Workflow Run from a non-payment app, as outlined in this demo use case. Do note that the triggerEventId in this case does not refer to a payment.
12345678910111213141516171819202122
{ "eventType": "WORKFLOW_RUN.FAILED", "version": "1.0", "date": "2024-02-22 12:12:12.121287", "primerAccountId": "123abcde-99f2-416e-8013-6ecd1c1285c3", "triggerEventId": "O-45276805409793-TZ", "workflow": { "id": "ccc8c3cc-805c-4d97-826e-ef8d4cc3d2a2", "name": "Create tickets for fraud suspected declines", "version" : 2 }, "run": { "timestamp": "2024-03-07T12:20:14.394429", "id": "dd1d9af0-1acf-42c1-a72f-d1234dd40465e", "status": "FAILED", "lastError": { "applicationId": "FRESHDESK", "actionId": "create_issue", "message": "Project key TEST not found" } }}
As there is no other information to query in this case, you have to inspect the Workflow Run Timeline to debug.