The Mesh Webhook Distribution Service enables subscribers to receive real-time updates from Mesh. By creating a webhook subscription, you will receive notifications when a specified event occurs on a resource. For example, you can subscribe to receive notifications to your application when a new account is created or an account is updated in Mesh. A notification is triggered when the event you subscribed to occurs and is sent to your application with a POST request.

Resources and Events

Webhook subscriptions and events are available for the following resources. You may also subscribe to "all" resources.

accounts

customers

documents

stop-payments

transactions

transfers

Using the Webhook Service API

To subscribe to an event or list of events on a resource, you will specify the resource and events you would like to subscribe to with the POST Create Subscription API. You must specify the endpoint where notifications will be sent, and a signing key to be used to generate a signature with each notification. You may also specify banks and cores you would like to receive event notifications for. If no signing key is provided, one will be generated. If no events, resource, banks or cores are provided, they will default to "all".

{
    "endpoint": "https://yoursite.com/yourEndpoint",
    "signingKey": "g@hK4Gv$cC4Jg!vS6Tn*iT8Wh^yW2Pr^uD7Vv#gU0Jb@vL5Oo!tE7Jv#pV5Ub$u", // Suggested to have a unique signingKey per subscription
    "resource": "accounts",
  	"events": [
        "create",
        "update"
    ],
 	  "banks": [
      	"all"
    ],
  	"cores": [
      	"all"
    ]
}

📘

Signing Keys

Each subscription requires a signingKey. The signingKey will be used to create the signature to validate notifications. If a signingKey is not supplied on creation of a subscription, one will be assigned automatically. The signingKey must be between 16 and 64 characters and contain only lowercase and uppercase letters, numbers, symbols (!@#$^&*-).

Receiving Notifications

When you are subscribed to an event on a resource, your endpoint will receive POST notifications. The notification will include a POST request body and headers.

Notification POST request body

{
  "resource": "accounts", // The subscribed resource
  "value": {"accountId":"123456789", "accountType":"CHECKING", "timestamp":1686323241908 } // Event details
}

Notification Request Headers

Validating the Signature

Your application should validate the notification it receives with the signature header. The following sample code provides an example of how to generate the signature using a signingkey. The signature you received in the header and the one you generate using the sample code should match.

import crypto from 'crypto';
const str2ab = require('string-to-arraybuffer');

async function createSignature(signingKey: string, body: any) : Promise<boolean> {
  const byteArray = str2ab(JSON.stringify(body));
  const emKey = Buffer.from(signingKey, 'ascii');
  const hmac = crypto.createHmac('sha256', emKey);
  const arr = new Uint8Array(byteArray);
  hmac.write(arr);
  hmac.end();
  const hmacHash = hmac.read().toString('base64');
  return hmacHash;
}

Retries

Your application should return an acknowledgement response to the webhook notification request within 15 seconds of receiving the request. If an acknowledgement response is not received, the webhook notification request will be retried 4 times for a total of 5 POST calls. These retries will be done in a Fibonacci sequence as shown below. After 5 calls, the retries will cease and details will be logged.