Webhooks
Setting up your Webhook-Config
Every Organization
is created with a webhook-config that is initially disabled. In order to enable the webhooks-config and select what events you want notifications for, you'll need to make a PATCH
call:
PATCH /api/organization/v1/current-organization/webhook-config
{
"url": "https://webhook.site/a5k730Q4", //Your receiving webhook server
"enabled": true,
"sharedSecret": "A7B6Fgl2KFI921gJ", //set a shared secret for webhook notification encryption
"webhookTypes": [
"payment", "kyc"
] // webhook types are "payment","transaction", "nft", "kyc", "document", "custodialAccount", "externalAccount", "identity", "asset", "wallet"
}
It's important to note that you'll only receive webhooks for the types that you have added to the webhookTypes
array.
Webhook structure
Here's an example of what a received webhook looks like:
{
"organizationId": "cbbb36e0-f507-40e8-a839-c8982de5c2da", //your integrator's organization
"action": "string", //
"id": "b3b3318e-fb35-49f6-a115-416f4e76c26c", //webhook id
"resourceId": "9c32c0d8-3e73-4896-8a7a-766c7428ac54", //API object's id to be referenced
"resourceType": "Payment", //API object that was either created or updated
"createdAtUtc": "2022-03-28T11:14:11.3704804+00:00", //webhook creation time
"changes": null //depending on the product suite, will either show "null" or key:value updates. Even a "null" value can have updates in the API but not present on the webhook object.
}
Whenever you receive a webhook, you should follow up with a GET
call in the api, targeting the resourceType
/resourceId
in the URL. You'll then be able to register the new object information in your DB/Front End, or make note of any changes to an existing object.
Webhook security
You might have noticed when updating your webhook-config that it asks for a sharedSecret
. The shared secret is hashed out with the contents of the webhook to create an encrypted value that is sent in the header of the webhook. This gives you confidence that the webhook did indeed come from our Fortress server. The verification formula looks like so:
Base64Encode(Hmac-Sha256(sharedSecret, webhookPayload))
The value of the encryption is to the key x-fortress-webhook-hmac
in the webhook header. Here's a sample curl response from a sent webhook.
curl -X 'POST' 'https://webhook.site/4de14c2c-9e4b-4a5a-b667-64a69f6da52f'
-H 'connection: close'
-H 'content-length: 266'
-H 'content-type: application/json; charset=utf-8'
-H 'traceparent: 00-317ed7516d09f1d424c95356ab4b377c-f194513ac07d6453-00'
-H 'request-id: |317ed7516d09f1d424c95356ab4b377c.f194513ac07d6453.'
-H 'request-context: appId=cid-v1:ec7b73c7-a50e-4e10-9be2-e81e0dd8abc2'
-H 'x-fortress-webhook-hmac: iM+cYc+/bpcBU2He+SBR+mIT1ngSre5cCx+rKSp+Nhk='
-H 'host: webhook.site'
-d $'{"organizationId":"083a1c85-0aed-4159-bf04-8b2a3f878f19","action":"create","id":"a7d247e2-9caf-42f0-b2a0-7cf55e09b954","resourceId":"cb822ebb-d273-4fd3-a0b4-622103fd6ab4","resourceType":"Transaction","createdAtUtc":"2022-05-25T21:21:55.0782343+00:00","changes":null}'
Updated 10 days ago