Journeys: Webhooks

The Journeys Overview states that a Journey Application can be initiated by calling a single API endpoint. You may be thinking, “how will we know the status of the Journey Application programmatically if we only make one API call and an applicant is moving through one or more workflows?”. The status of a Journey Application can be observed in the Alloy dashboard, but from a developer perspective the answer is webhooks. While Journeys always provide a synchronous response, they are accompanied by webhooks which allow for reliable and resilient processing of status update events into your system of record. A listener can be configured to receive all of these status updates. The final and most important webhook communicates a completed_application status for the Journey Application.

How to Configure Journey Webhooks

Within the Alloy dashboard, Journey webhooks can be configured by navigating to Settings > Webhooks > + Webhook.

On the Create Webhook modal, complete the following:

• Enter a Name.
• In the Select a trigger action drop-down, choose one of the following (live or sandbox):
  • Notify on live journey application status change
  • Notify on sandbox journey application status change
• Enter the URL for the listener endpoint.
• Under Advanced Settings > Authentication type, the default selection is None. Optionally, to authenticate these webhooks, select Basic or OAuth2.0 from the drop-down.
  • Basic
    • Enter a Username and Password.
  • OAuth2.0
    • Under Grant Type, select one of these two:
      • Client Credentials
      • Password
    • If Client Credentials is selected, the following fields are required and optional:
      • Required
        • Client ID
        • Client secret
        • Token URL
        • Access Token Encoding
          • Select URL Encoded or JSON from the drop-down.
      • Optional
        • Scope
        • Audience
    • If Password is selected, the following fields are required:
      • Required
        • Client ID
        • Client secret
        • Token URL
        • Username
        • Password
        • Access Token Encoding
          • Select URL Encoded or JSON from the drop-down.
• Under Advanced Settings > Method, select one of the following:
  • POST
  • PATCH
  • PUT
• Under Advanced Settings > Headers (optional), enter values for any needed headers.
  • Click Add Another Header to include multiple headers.
• Under Advanced Settings > Extra JSON data (optional), enter any desired additional JSON to be included in the webhooks.
• Click TEST WEBHOOK to try the functionality.
  • Note: Testing webhooks currently works if None or Basic is selected for Authentication type, but not if OAuth2.0 is selected.
    • When testing the webhook, the Test Request Data and a Test Response is displayed. See the GIF below.
• Click Create to complete the webhook configuration.

Workflow Asynchronous Webhook

If you are using a Journey or a stand-alone workflow which contains a service that can take a long time to complete (an asynchronous service), you will need to configure the Notify on Asynchronously Updated Evaluation webhook for the respective workflow. This is the only webhook type which requires configuration at the workflow level. You can follow the steps above to create the webhook, selecting the appropriate trigger action (Notify on Asynchronously Updated Evaluation). Once the webhook has been created, it can be associated with the workflow on the workflow overview page by clicking +ADD WEBHOOK under Workflow Asynchronous Webhook.

After clicking +ADD WEBHOOK, select the webhook that was just created on the Workflow Asynchronous Webhook modal and click Save: