Overview
Webhooks provide a mechanism for notifying your integration in response to changes in the First AML platform.
Webhooks can be managed directly via the API using the createWebhookSubscription and deleteWebhookSubscription mutations. These mutations require the api-management scope to be granted to your API client.
The targets of an existing webhook subscription can be managed using the addWebhookSubscriptionTarget and removeWebhookSubscriptionTarget mutations. These allow you to add or remove organization/office targets without recreating the subscription.
Webhooks must be configured with a https:// destination URL, http:// is not supported.
Types
The following webhook types are supported:
- CaseCreated
- CaseStatusUpdated
- PdfUpdated
- VerificationReportGenerated
- UnwrapStatusUpdated
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 downloaded.
{
"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"
}
Unwrap Status Updated
{
"eventType": "UnwrapStatusUpdated",
"caseId": "12345",
"status": "New|InProgress|Completed|Stopped|Failed|CantContinue|Skipped"
}
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 a verifier token key is generated, this will be a Base64 encoded value, an example of this would be RXD1PO5RcE+/Ku0I9N6mPihk6L4kQTHUx39qtOHu4Wc=. You can retrieve this key by querying the verificationKey field on the WebhookSubscription type.
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 algorithm. 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.
IP Addresses
If you need to allowlist the IP addresses that webhook requests originate from, the following addresses are used per environment:
| Environment | IP Addresses |
|---|---|
| Sandbox | 54.253.106.106 |
| APAC Production | 3.104.113.70, 3.104.204.122 |
| EU Production | 18.203.112.133, 34.241.253.14 |
Setup
Webhooks can be managed directly via the API using the createWebhookSubscription and deleteWebhookSubscription mutations. These mutations require the api-management scope to be granted to your API client.
Once a webhook subscription has been created, you can manage its targets using the addWebhookSubscriptionTarget and removeWebhookSubscriptionTarget mutations to add or remove organization/office targets.
The verificationKey used for webhook security verification is available on the WebhookSubscription type and can be queried directly from the API after creating your webhook subscription.
