Callbacks / Webhooks

Workflow Callbacks are an optional feature which allow your application to be notified of changes during routing. There are two types described below.

State Based Callbacks

You can elect to receive a callback that will inform your application when an package changes routing state. This would occur any time an packages starts routing, completes routing, is voided, etc.

To enable this type of callback, set the Application Callback URL via the form Dashboard under the Configuration tab. You can configure a callback per form environment.

Route Based Callbacks

For a bit more control, you can add a callback to your form's route. Workflow will send a callback to your application when each package arrives at the configured stop during routing. You can setup multiple destination callbacks within your route.

Continue Routing

Callbacks with this option will not impact the current route. Your application will be notified and packages will continue to route without further action.

Freeze Routing

You can elect to freeze routing after a callback is sent. This is useful if you need to edit entry data or run processes within your system before routing resumes. Once a route is frozen, it will not resume routing until Workflow receives notification from your system to resume routing.

Unfreezing Routes After Callback

The callback will include a lockId attribute. You will need this id to unfreeze the routing so that the package can continue on its routing path.

Request URL

DELETE https://apps.its.uiowa.edu/workflow/{env}/api/developer/forms/{formId}/packages/{packageId}/notification_locks/{lockId}

Callback Format & Information

All callbacks share the same format other than the entry format. Entry format is determined by form type i.e. Developer vs Form Builder because form builder forms support multiple answers per field. See formatting below.

Workflow will send a POST request to the given callback URL in the following JSON formats. If the callback fails, you'll need to contact support to have it retried.

The state attribute can have the following values.

State	Description
PRE_ROUTING	The package is not routing and is either not yet submitted or was removed by an admin/application
DRAFT	The package is not routing and is awaiting the initiator to submit/re-submit
ROUTING	The package is currently routing
COMPLETE	The package has completed routing
VOID	The package has been voided and is no longer routing

Examples

Developer

{
    "@class" : "developer",
    "formId" : 100,
    "packageId" : 12345678,
    "state" : "COMPLETE",
    "createdAt" : "2025-05-24T17:04:48",
    "stop" : null,
    "lockId" : 123456,
    "entry" : {
        "field_1_naturalKey": "field_1_value",
        "field_2_naturalKey": "field_2_value"
    }
}

Form Builder

{
    "@class" : "form_builder",
    "formId" : 100,
    "packageId" : 12345678,
    "state" : "COMPLETE",
    "createdAt" : "2025-05-24T17:04:48",
    "stop" : null,
    "lockId" : 123456,
    "entry" : {
        "field_1_naturalKey": ["field_1_value1", "field_1_value2"],
        "field_2_naturalKey": ["field_2_value"]
    }
}

Callbacks and Firewalls

If your application is not receiving the callbacks you've configured, your application is possibly unreachable by Workflow for one of the following reasons.

• Your application may be behind a firewall that is blocking the Workflow servers. Please contact your network support team and confirm that your network firewall is not blocking any of Workflow's ip addresses below.
• If your application is not hosted on the UI network, Workflow may need to configure callbacks to your host to go through the proxy. Please reach out to us in this case.

Workflow IPs

128.255.67.172
128.255.67.173
128.255.67.174
128.255.67.175
128.255.67.176

Verifying Callbacks NEW

Changes have been made to enhance the callback verification process by utilitizing an asymmetric key pair. The authenticity and integrity of messages can now be verified based on a single signature value that is generated in the same way for all clients. No more per form secrets! 💯

To verify callbacks, developers can follow these simple steps:

1. Understand the Signature: When Workflow posts a callback to your application, it will now include the header x-workflow-verification. This new header contains a signature value that is generated using the Ed25519 algorithm and Workflow's private key.

2. Obtain the Public Key: Workflow provides a convenient endpoint for retrieving it's public key that developers must use to verify the signature. That endpoint is:

GET     /api/v2/public-key

3. Verify the Signature: Extract the siganture from the x-workflow-verification header from the callback request. Use the Ed25519 public key to verify the signature against the callback payload (the body of the request). This process ensures that only authentic and untampered callbacks are processed by your application.

Tip

Every language/framework is different. Make sure to use a Cryptographic Library that supports Ed25519 to perform the verification. Don't know a library? Ask AI e.g. GitHub Copilot for the code in your language of choice! 😉

4. Keep the Public Key Updated: It is highly recommended that you cache the value of the public key rather retrieving it with each callback. However, Workflow may infrequently rotates its keys for security purposes. To allow for this possibility, if a callback fails verfication, refresh the your copy of the public key and retry verification before completely rejecting the request. If the signature verification fails again, reject the callback as it may have been tampered with or is not from Workflow.