A trigger is a way to fire a workflow from a payment event. The trigger is linked to a unique workflow that will be executed only if its filter condition is satisfied. If so, it will forward values from the event to the workflow in a set of configured variables corresponding to the ones expected in the workflow.
Creating a trigger#
To create a trigger, use the Create Trigger endpoint:
fctl orchestration triggers create <event> <workflowID>Filter syntax#
The syntax for the filter is based on the expr-lang expression language.
Example filter:
event.type == "PAY-IN" && event.provider == "PROVIDERID" && hasPrefix(event.rawData.merchantReference, "test") == trueTesting a trigger#
Before deploying a trigger to production, you can test it to verify that the filter matches correctly and that variables are extracted as expected.
Use the Test Trigger endpoint. The payload should be the payment event you want to test against:
curl -X POST $FORMANCE_API_URL/api/orchestration/v2/triggers/<trigger-id>/test \
-H "Content-Type: application/json" \
-d '{
"id": "dummyValue",
"type": "PAY-IN",
"asset": "EUR/2",
"amount": 4199,
"scheme": "visa",
"status": "SUCCEEDED",
"rawData": {
"amount": {
"value": 4199,
"currency": "EUR"
},
"reason": "012789:0000:03/2030",
"success": "true",
"eventCode": "AUTHORISATION",
"eventDate": "2023-12-15T15:22:32+01:00",
"operations": [
"CANCEL",
"CAPTURE",
"REFUND"
],
"pspReference": "XXXXXXXX",
"paymentMethod": "visa",
"additionalData": {
"authCode": "789789",
"expiryDate": "03/2030",
"cardSummary": "0000"
},
"merchantReference": "XXXX",
"merchantAccountCode": "XXXXX"
},
"metadata": {},
"provider": "PROVIDERID",
"createdAt": "2023-12-15T15:22:32+01:00",
"reference": "XXXXXX",
"connectorId": "connectorID",
"initialAmount": 4199
}'The response shows whether the filter matched and the extracted variable values:
{
"data": {
"filter": {
"match": true
},
"variables": {
"amount": { "value": "4199" },
"asset": { "value": "EUR/2" },
"merchantID": { "value": "001" },
"paymentID": { "value": "dummyValue" },
"userID": { "value": "003" }
}
}
}Evaluating metadata in triggers#
You can use link() and get() functions to retrieve metadata from related accounts in your trigger variables and filters.
Accessing account metadata#
To retrieve metadata from a payment's associated account:
{
"event": "SAVED_PAYMENT",
"workflowID": "xxx",
"vars": {
"myVar": "get(link(event, \"destination_account\").metadata, \"foo\")"
}
}This example retrieves the foo metadata field from the destination account linked to the payment event.
Webhooks#
You can create webhooks to get notified of Flows events, whether they succeed or fail:
| Event | Description |
|---|---|
STARTED_WORKFLOW | Workflow instance has started |
SUCCEEDED_WORKFLOW | Workflow instance completed successfully |
FAILED_WORKFLOW | Workflow instance failed |
STARTED_WORKFLOW_STAGE | A workflow stage has started |
SUCCEEDED_WORKFLOW_STAGE | A workflow stage completed successfully |
FAILED_WORKFLOW_STAGE | A workflow stage failed |
SUCCEEDED_TRIGGER | Trigger fired successfully |
FAILED_TRIGGER | Trigger failed to fire |
You can find the complete list of available events in the Formance events repository.