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}'