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 fieldDescription
eventTypeWORKFLOW_RUN.FAILED for failed runs. We might support additional types in the future.
versionWebhook version for this eventType.
dateDate and time when the webhook event was sent.
primerAccountIdPrimer Account ID of the account that belongs to the failed run.
triggerEventIdAn 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 / idThe ID of the workflow that had a failed run.
workflow / nameThe name of the workflow that had a failed run.
workflow / versionThe version of the workflow that had a failed run.
run / timestampDate and time when the workflow run failed.
run / idThe ID of the workflow run that failed. This can be used to easier access the workflow run in the dashboard.
run / statusThe Workflow Run status will always be FAILED currently. In the future, COMPLETED might become an additional option for Workflow Run Webhooks.
lastError / aplicationIdThe 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 / actionIdThe 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 / diagnosticsIdA diagnostics ID helping Primer to debug traces when needed (optional).
lastError / messageThe 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:
JSON
{
  "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. Do note that the triggerEventId in this case does not refer to a payment.
JSON
{
  "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.