Configure

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 is a JSON array of webhook payloads. Use the ids in the payload to query the API for the latest state. transaction.created includes the transaction fields listed on the webhook types page. Other events often include only an id.

Webhook Payloads

This is the exact body of one firm.updated delivery. The signature below is computed over these bytes.

[{"data":{"firm":{"id":"fcab45p5-c4cb-427d-a144-b3f11f227658"}},"eventId":"2e9e4123-9568-4f34-9ae2-836f760f03b8","firmId":"fcab45p5-c4cb-427d-a144-b3f11f227658","type":"firm.updated"}]

Formatted, that body is:

[
  {
    "data": {
      "firm": {
        "id": "fcab45p5-c4cb-427d-a144-b3f11f227658"
      }
    },
    "eventId": "2e9e4123-9568-4f34-9ae2-836f760f03b8",
    "firmId": "fcab45p5-c4cb-427d-a144-b3f11f227658",
    "type": "firm.updated"
  }
]

Payload Fields

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.

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.

string

required

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

string

required

The unique id for this event. This can be used as an idempotent 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 include an HMAC signature in the X-SIGNATURE header. HTTP libraries often expose that header as x-signature. Use it with the webhook secret from the Partner Portal to verify the body was not changed. X-SIGNATURE is the base64 HMAC-SHA512 of the exact UTF-8 request body, using the webhook secret as the key. Check the signature against those bytes, then parse the JSON. Serializing a parsed object again can change key order or whitespace, and the signature will not match. The algorithm is HMAC-SHA512. The key is the webhook secret. The digest is base64. For the sample body above and the sample secret whsec_example_9f3c2a, X-SIGNATURE is:

Sq5Cf9I5x/HZoYAV1xnpUq2Pz9YJ1zbk8Y++eIpd8U7blOwtowPh30soVTSBC36g43QyCiQ/6DyT1z+GMMPsig==

Verify with the raw body:

import crypto from "crypto";

export function verifyHmacSignature(
  rawBody: Buffer | string,
  webhookSecret: string,
  xSignatureHeader: string
): boolean {
  const hmac = crypto.createHmac("sha512", webhookSecret);
  hmac.update(rawBody);
  return hmac.digest("base64") === xSignatureHeader;
}

Read the body before a JSON parser runs. With Express, use express.raw() for this route:

app.post(
  '/webhooks/confido',
  express.raw({ type: 'application/json' }),
  (req, res) => {
    const rawBody = req.body.toString('utf8');
    const ok = verifyHmacSignature(
      rawBody,
      process.env.CONFIDO_WEBHOOK_SECRET,
      req.get('x-signature')
    );

    if (!ok) {
      res.status(401).send('invalid signature');
      return;
    }

    const events = JSON.parse(rawBody);
    res.status(200).send('ok');
  }
);

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.

Event history and resend

Partners can inspect recent delivery attempts for a registered webhook URL and manually trigger a resend:

In the Partner Portal, open your webhook configuration and use the event list for that URL (including failed and dead-lettered events) to resend a payload.
Via the GraphQL API (authenticated as a Partner Admin), use the webhookEventsList query (scoped to a webhookUrlId) to list events, and the webhookEventResend mutation to retry delivery for a specific eventId.

Use eventId from the webhook body as your idempotency key when processing. Resends reuse that same eventId, so duplicate delivery should be safe if your handler is idempotent. There is no separate “replay all since timestamp”; for large gaps, combine polling the API with portal resends, or contact support if you need operational help after extended outages.

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.

Introduction

Firm Onboarding

Embedded Forms

Receive Money

Send Money (Disbursements)

Payment Methods

Cards

Payments Lifecycle

Hosted Fields

Statements

Webhooks

Sandbox

Webhook Payloads

Payload Fields

Configure Webhooks

HMAC Signature

Retry Policy

Event history and resend

Disabling Webhook URLs

​Webhook Payloads

​Payload Fields

​Configure Webhooks

​HMAC Signature

​Retry Policy

​Event history and resend

​Disabling Webhook URLs

Webhook Payloads

Payload Fields

Configure Webhooks

HMAC Signature

Retry Policy

Event history and resend

Disabling Webhook URLs