Webhooks notify you when things happen in Confido so your integration can react to them.

By registering webhook endpoints, you enable Confido to send webhook payloads as part of POST requests to these endpoints.

The body of these POST requests will contain a list of webhook payloads. The payloads contain minimal data and are meant to be followed by a query to our API to grab the specific data you need.

​
Webhook Payloads

Here is an example body with a single transaction.created payload. Notice how only the transaction.id was delivered. When processing this webhook, you’ll use this id to query our API and get the latest state of the transaction.

[
  {
    data: {
      transaction: {
        id: "9c2dbhy6-08d9-4d94-971b-8b594c2ea13c",
      },
    },
    type: "transaction.created",
    firmId: "fcab45p5-c4cb-427d-a144-b3f11f227658",
    eventId: "2e9e4123-9568-4f34-9ae2-836f760f03b8",
  },
];

​
Payload Fields

​
data
object
required

The data field contains the specific data for the webhook type. It is a JSON object that will vary based on the webhook event type.

​
type
string
required

The type of webhook event. This is a string value that defines the specific event that occurred, such as transaction.created, firm.updated, etc.

​
firmId
string
required

The id of the firm this webhook event is associated with.

​
eventId
string
required

The unique id for this event. This can be used as an idempontent key to ensure you do not take multiple actions for the same webhook event.

​
Configure Webhooks

You can register endpoints and configure which webhook types you are interested in through the Partner Portal under Settings > Webhooks.

You will not receive webhooks for types that are not selected.

​
HMAC Signature

Webhook requests will include an HMAC Signature under the X-SIGNATURE header. This can be used along with the webhook secret found in the Partner Portal to verify the webhook came from Confido and has not been tampered.

To verify the HMAC Signature, create a sha512 Hmac with your webhook secret, update it with the webhook payload, and ensure it is equal to the X-SIGNATURE header received with the webhook.

Here is some example code written in TypeScript.

import crypto from "crypto";

export function verifyHmacSignature(
  webhookPayload: WebhookPayload,
  webhookSecret: string,
  xSignatureHeader: string
): boolean {
  const hmac = crypto.createHmac("sha512", webhookSecret);
  hmac.update(JSON.stringify(webhookPayload));
  const hmacSignature = hmac.digest("base64");
  return hmacSignature === xSignatureHeader;
}

​
Retry Policy

If we do not receive a 200 level response while posting to your endpoint after 5 seconds, the webhook event enters a failed state. All webhook events in the failed state are retried with the following backoff strategy: 5 min, 20 min, 60 min, 1 day, dead letter.

​
Disabling Webhook Urls

If a webhook event dead letters, we check if the webhook url has received any successful responses in the last 24 hours. If it has not, we disable the webhook url and it must be re-enabled through our Partner portal.