Workflow Run failed

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 / applicationId	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:

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.

​Webhook setup

​Webhook payload

​Example for a payment workflow

​Example for any other workflow

Webhook setup

Webhook payload

Example for a payment workflow

Example for any other workflow