Connect Webhooks

The Connect webhook events are sent at different times during the Connect session while the customer is interacting with Connect or the MVS apps on your web and mobile application pages. You can track the status of Connect sessions, get information about customer usage, and receive notifications when certain processes are completed.

The MVS Financial app uses Connect webhooks, but there are a few webhooks used in the MVS Payroll and Paystub apps on the Webhooks Events List.

Send Webhooks-Retry

If a Connect notification is sent but not received, it will retry 5 times in 5 minutes then 1 time a day for 3 days, and then it stops trying to send altogether.

Note: Report webhooks are sent only one time.

See Report Webhooks

Webhook Event Body

All events include a wrapper that contains metadata about the event. The event data is within the payload key. Webhooks are sent if the webhookData parameter is specified in the body of the Generate 2.0 Connect URL Link request.

See Custom Webhooks

Sample event body
 }

"customerId":"12345678",

"consumerId":"ed81281fcec7ec557aa7d292a3188b75",

"eventType":"started",

"eventId":"1495468585434-0e73d1719173766fe4dfe1a8",

"payload":{},

"webhookData": {}

}

Preventing Spoofing

If you’re using webhooks for sensitive or critical information, we recommend that you verify the signature of the webhook.

The X-Finicity-Signature header gets added to every webhook sent. To verify the signature:

  1. Create a SHA-256 HMAC of the request body using your Partner Secret as the key. 
  2. Compare it to the signature included on the X-Finicity-Signature header. If the two are equal then the request is valid, otherwise, it is spoofed.

Store the eventId and ignore webhooks with an ID that have already been processed to prevent replay attacks.

Example: Signature Validation in Node.js.

Sample event body
 const crypto = require('crypto');

const partnerSecret = '{{PARTNER_SECRET}}';

router.use('/webhook-handler', (request, res) => {

  const body = request.body;

  const signature = crypto

    .createHmac('sha256', partnerSecret)

    .update(JSON.stringify(body))

    .digest('hex');



  if (request.get('x-finicity-signature') !== signature) {

    throw new Error('Spoofing detected, rejecting webhook');

  }

});