Webhooks

FinShare can POST a signed JSON event to your URL whenever something happens on a request: the owner opens the link, approves, a report is ready, access ends. Webhooks are signed with the Standard Webhooks scheme, so any Standard Webhooks library can verify them.

Add an endpoint

app.finshare.io/app/developers

12

1. 1API keysCreate and revoke keys for the /v1 API.
2. 2Signed webhooksStandard Webhooks signatures, retried for about two to three days.

Developers › Webhooks.

In the app:

Send test posts a signed ping event and shows the HTTP status you returned. Deliveries shows the last 25 deliveries to the endpoint with their status code, error and number of tries.

Over the API:

curl https://app.finshare.io/v1/webhook_endpoints \
  -H "Authorization: Bearer fl_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://app.example.com/webhooks/finshare", "event_types": ["request.approved", "report.ready", "round.delivered", "grant.revoked", "grant.expired"] }'

Returns 201 with { "id", "url", "event_types", "secret" }. GET /webhook_endpoints lists endpoints, DELETE /webhook_endpoints/:id removes one, and POST /webhook_endpoints/:id/ping sends a test.

What a delivery looks like

POST /webhooks/finshare HTTP/1.1
Content-Type: application/json
User-Agent: FinShare-Webhooks/1
webhook-id: evt_Qm7Tz2Kc9Vb4Xn8Rw3Lp
webhook-timestamp: 1793205631
webhook-signature: v1,K5oZfzN95Z9UVu1EsfQmfVNQhnkZ2pj9o9NDN/H/pI4=
 
{
  "id": "evt_Qm7Tz2Kc9Vb4Xn8Rw3Lp",
  "type": "report.ready",
  "created_at": "2026-10-28T16:40:31.000Z",
  "data": {
    "request_id": "req_8fK2mQ7xLp3vRt9WnB4c",
    "external_ref": "deal-4471",
    "round_number": 1,
    "report": {
      "id": "rpt_Vn4Qx8Lm2Tb6Wk9Rc3Hp",
      "report_type": "profit_and_loss",
      "title": "Profit and Loss",
      "period_start": "2023-01-01",
      "period_end": "2025-12-31",
      "basis": "accrual",
      "company_name": "Ortiz Plumbing LLC",
      "status": "ready",
      "files": {
        "xlsx": "https://app.finshare.io/v1/reports/rpt_Vn4Qx8Lm2Tb6Wk9Rc3Hp/file?format=xlsx",
        "csv": "https://app.finshare.io/v1/reports/rpt_Vn4Qx8Lm2Tb6Wk9Rc3Hp/file?format=csv",
        "json": "https://app.finshare.io/v1/reports/rpt_Vn4Qx8Lm2Tb6Wk9Rc3Hp/file?format=json"
      }
    }
  }
}

Every event body has id, type, created_at and data. data always has request_id and external_ref (your id, or null). The files URLs need your API key; fetch them from your server.

Events

Under a connector, events about a pull carry the pull's request_id and external_ref, and round.approved also includes connector_request_id. See Connector mode.

Test pings have "type": "ping" and empty data.

Verify the signature

The signature is an HMAC-SHA256 over "<webhook-id>.<webhook-timestamp>.<raw body>", keyed with your secret. The key is the base64-decoded part of the secret after whsec_. The webhook-signature header is v1, followed by the base64 digest, and may hold several space-separated signatures.

Verify against the raw request body, before parsing it as JSON.

import { createHmac, timingSafeEqual } from "node:crypto";
 
export function verifyFinShare(secret, headers, rawBody) {
  const id = headers["webhook-id"];
  const ts = headers["webhook-timestamp"];
  const sigs = headers["webhook-signature"];
  if (!id || !ts || !sigs) return false;
  // Reject anything more than 5 minutes off, to stop replays.
  if (Math.abs(Date.now() / 1000 - Number(ts)) > 300) return false;
 
  const key = Buffer.from(secret.replace(/^whsec_/, ""), "base64");
  const expected = Buffer.from(
    "v1," + createHmac("sha256", key).update(`${id}.${ts}.${rawBody}`).digest("base64"),
  );
  return sigs.split(" ").some((s) => {
    const b = Buffer.from(s);
    return b.length === expected.length && timingSafeEqual(b, expected);
  });
}

Delivery and retries

• Return any 2xx within 10 seconds to acknowledge. Anything else, including a redirect or a timeout, counts as a failure.
• Failed deliveries are retried with exponential backoff, up to 12 attempts over roughly two and a half days.
• Delivery is at least once. Store the webhook-id and ignore repeats.
• Events can arrive out of order. Use created_at, or fetch GET /requests/:id for the current state.
• Do the work in a background job. Acknowledge first, then download files.

Events are recorded in the same database transaction as the change that caused them, so you never get an event for a change that didn't stick.

A typical handler

1. Verify the signature. Reject with 401 if it fails.
2. If you've seen this webhook-id, return 200 and stop.
3. Record the id and enqueue a job. Return 200.
4. In the job, switch on type. For report.ready, download data.report.files.xlsx with your API key and attach it to the record matching external_ref.

Related

• Creating requests
• Embedding