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
The following webhook types are supported:
- CaseCreated
- CaseStatusUpdated
- PdfUpdated
- VerificationReportGenerated
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.
The body of the webhook is encoded as application/json and delivered via a POST request sent to the target URL.
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.
Case Created
{
"eventType": "CaseCreated",
"caseId": 12345,
"officeKey": "abc456789-3476-4cf6-8491-bdd1272cf01"
}
Case Status Updated
{
"eventType": "CaseStatusUpdated",
"caseId": 12345,
"officeKey": "abc456789-3476-4cf6-8491-bdd1272cf01"
}
Pdf Updated
The pdfUrl is a link to the api, where the document can be downloded.
{
"eventType": "PdfUpdated",
"caseId": 12345,
"pdfId": 12345,
"pdfUrl" : "https://api.firstaml.com/pdf/document",
"status": "Completed|Failed"
}
Verification Report Generated
Only one of individualId and entityId will be populated. The other value will be set to null
{
"eventType": "VerificationReportGenerated",
"caseId": "12345",
"individualId": "12345",
"entityId" : "12345"
}
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).
