Overview
Currently you need to contact First AML customer support to have a webhook setup.
Webhooks must be configured with a https:// destination URL, http:// is not supported.
Webhooks provide a mechanism for notifying your integration in response to changes in the First AML platform.
Types
Currently 2 webhook types are supported:
- CaseCreated
- CaseStatusUpdated
Webhooks need to be configured to target a specific organization. The webhook can also be restricted to only respond to events for a subset of offices within an organization as well.
Webhook Body
The body of the webhook is encoded as application/json and delivered via a POST request sent to the target URL. For each event, the webhook payload will contain the following information:
{
"eventType": "CaseCreated",
"caseId": 12345,
"officeKey": "abc456789-3476-4cf6-8491-bdd1272cf01"
}
You will note that the contents of the webhook payload does not include any details about the case or data that was changed. You must make a secured request to retrieve any details related to the case in response to receiving a webhook.
Security
To ensure requests you receive come from First AML you can verify the webhook via the signature provided in the x-faml-signature header. When your webhook is registered we will provide you with a verifier token key, this will be a Base64 encoded value, an example of this would be RXD1PO5RcE+/Ku0I9N6mPihk6L4kQTHUx39qtOHu4Wc=.
To verify the signature, you need to create your own and compare it to the contents of the x-faml-signature. To do this you need to use the HMACSHA256 algorithmn. Most languages have a library for this.
Creating the signature requires inputs in the form of two byte arrays:
- The Base64 decoded
verifier token keyas the secret key - The UTF-8 encoded contents of the request body
This should output a signature as a byte array. Base64 encode this output. If the request is from First AML, this should match the contents of the x-faml-signature header.
Some libraries will take strings as inputs or give a string as the output. For these it’s important you check the encoding to ensure it matches the process listed above.
An example using the key RXD1PO5RcE+/Ku0I9N6mPihk6L4kQTHUx39qtOHu4Wc= and the webhook request body being:
{"eventType":"CaseCreated","caseId":3036,"officeKey":null}
Then the value of the x-faml-signature would be S6P+iWJWILHg+vLc7tkSlzVD3YAouOeyFb1gEvdAoZc=.
Redelivery
If the target endpoint does not return a 200 OK response, or is not available, delivery of the webhook will be reattempted up to 5 times within a half hour before webhook delivery is abandoned.
If required, a request can be made to the support team upon request to reattempt delivery of failed webhooks.
Requesting Setup
When you are ready to configure a webhook, please provide the following details to your primary support contact to get your webhook set up.
- Webhook Destination URL (Must be HTTPS)
- Webhook Event Types
- The environment the webhook subscription should be created for (Production or Sandbox).
