Webhooks

Server-to-server partner events for embedded integrations.

Some partner integrations need to update Jupid outside the iframe login flow. Jupid enables those webhooks per partner and sends separate staging and production webhook URLs and HMAC secrets.

Webhooks are server-to-server only. Do not call them from browser code.

Account changes

The first supported partner event is accounts.changed. Use it when the partner knows a user's account list has changed and Jupid should sync the latest snapshot.

Jupid currently expects the same durable user ID in webhook sub that the partner uses in the embed JWT sub. The user must have opened the embed at least once so Jupid has a partner-user mapping.

POST https://backend.jupid.com/api/webhooks/alwaysbank
Content-Type: application/json
x-jupid-signature: <hex hmac>

Jupid sends the exact URL for each enabled partner and environment. For staging, use the staging backend URL provided by Jupid.

Request body

Send a full current account snapshot:

{
  "type": "accounts.changed",
  "sub": "stable-partner-user-id",
  "payload": {
    "tier": "paid",
    "business": {
      "id": "business-123",
      "name": "Acme LLC"
    },
    "accounts": [
      {
        "id": "account-123",
        "name": "Operating Checking",
        "number": "****1234",
        "type": "checking",
        "currency": "USD",
        "current_balance": 12000.34,
        "plaid_token": "<optional-partner-provided-plaid-token>",
        "status": "active"
      }
    ]
  }
}

The payload shape is the same account-list payload described in Authentication. Accounts missing from a later full snapshot can be treated as disabled.

Signatures

Jupid verifies x-jupid-signature as a hex HMAC-SHA256 digest over the raw request body.

import { createHmac } from "node:crypto"

const signature = createHmac("sha256", webhookSecret)
  .update(rawRequestBody)
  .digest("hex")

Use the exact bytes sent over HTTP as rawRequestBody. Reformatting JSON after signing changes the digest.

Responses

Retry non-2xx responses with backoff. Full snapshots are preferred because they make retries and duplicate delivery safe.

Timing

Send accounts.changed as soon as practical after the account list changes. If a webhook is sent before the user has ever opened the embed, Jupid cannot map the partner user yet; send another full snapshot after the first successful embed login.