Integrate AMPLIFY Choreography event webhooks

AMPLIFY Choreography provides a robust choreography experience by supporting the execution of choreography based on certain events and / or scheduled activities. To accomplish this, Amplify Choreography offers webhooks that can communicate with user-configured event / scheduler services.

Use the webhook subscription to send events that trigger the execution of choreography or a single step. The subscription also enables webhook clients to consume notifications about events during the execution of the choreography / step. To achieve this integration, webhook clients must expose an endpoint where the AMPLIFY Choreography runtime sends the payload for the event notification.

For AMPLIFY Choreography webhook integration, webhook clients must be registered on AMPLIFY Choreography. The webhook client uses the AMPLIFY Choreography service account for generating a key and secret for authentication. Events are received from the clients through the AMPLIFY Choreography runtime webhook and notification for execution events is sent to the webhook clients notification webhook defined by the client.

Before you start

Install Axway AMPLIFY CLI.

Objectives

Use CLI commands to create a webhook service account and client, then implement the integration.

Configure the event webhook integration

To configure the webhook integration, you must create a service account and a webhook client. See for additional CLI commands not covered in this topic.

Create a service account

Use AMPLIFY Choreography CLI to create a service account:

amplify ace serviceaccount <Service Account Name>

The output of the command returns the service account ID, which is used to retrieve the generated APIKey and Secret using the following Amplify Choreography CLI command:

amplify ace serviceaccount --id=<Service Account ID>

The output of the command returns the APIKey and Secret that the webhook client uses to configure the authentication.

For additional APIKey service account CLI Commands, see Manage APIKey service accounts.

Create the webhook client

Use AMPLIFY Choreography CLI to create / register the webhook client and associate the service account:

amplify ace webhookclient add

When prompted, enter:

  • Webhook Client Name
  • Service Account ID
  • Notification Webhook URL

Implement the webhook client

After the webhook client is configured, the webhook client is implemented by exposing an endpoint for Event notification and calling the runtime webhook.

ACE Runtime Webhook

Endpoint : <ACE Runtime URL>/executive/webhook

Method: POST

Events:

Event Type Description
execute.choreography Event to trigger the execution of the defined choreography
execute.step Event to trigger the execution of a registered service

Payload:

Field Description
eventType Webhook event type
name Name of the choreography or service to execute
version For execute.step event, version of the service to execute
payload Base64 encoded content to be passed as input for the execution of choreography / step
locationReference Boolean value indicating that payload is a location reference or raw content
metadata (Optional) Object with string key / value pairs
traceContext (Optional) Base64 encoded OpenTracing context to be used for creating spans

Authentication:

Header Value
X-Client-ID ID of the client for webhook subscription
APIKey API key generated for the webhook client

Notification webhook

Endpoint : Defined by webhook client

Method: POST

Events:

Event Type Description
response.choreography.step Event generated when a service executing in choreography produces the output. The event is generated for each output produced
response.step Event generated when executing a service produces the output. The event is generated for each output produced
processing.choreography.step.completed Event generated when processing on the leaf service in choreography execution is completed. The event is generated for leaf service in choreography
processing.step.completed Event generated when processing on the service execution is completed
processing.choreography.step.error Event generated when service processing in choreography execution fails
processing.step.error Event generated when processing fails on service execution

Payload:

Field Description
eventType Webhook event type
executionId ID of the choreography / step execution
payload Base64 encoded content resulting from the execution of servic
locationReference Boolean value indicating that payload is a location reference or raw content
metadata Object with string key / value pairs
traceContext Base64 encoded OpenTracing context to be used for creating spans

Authentication:

Header Value
X-Auth-Signature Signature created using HMAC-256 algorithm and the secret generated for the webhook client. Webhook clients can validate the signature with the configured secret

Related Links