Webhooks

Lucra POSTs an event to your server when something changes, so you don't have to poll. Webhooks belong to an API key: each key has at most one webhook URL.

Set up

Add a webhook URL when you create the key in Settings → Developers → API, or have the key set its own:

const { data } = await lucra.keys.current.update({
  body: { webhookUrl: "https://example.com/lucra/webhooks" },
})

The response's webhookSecret (whsec_…) is the signing secret, shown only once; store it to verify signatures. Setting a URL again issues a new secret, and null stops events. GET /v1/keys/current reads the current URL.

Which events a key gets

A key gets events about its own account. A partner's key also gets events about its client brands, and every event about a creator on its roster (in data.creator), wherever it happens: their applications, submissions, messages, retainers, payments, connections and payout setup. An event about a creator alone has account: null.

Missed some? GET /v1/events lists the events sent to the key's webhook, newest first, each with its delivery status. It holds only events from while the key had a webhook URL.

Events

An event names what changed and the IDs involved; fetch the details from the API. Ignore types you don't handle, since new ones are added.

{
  "id": "evt_0u5s9xZIdD99WBwmDjJPYc3",
  "type": "submission.approved",
  "account": "acct_04Jm0JWUg20EhYo2lyNIEHo",
  "data": { "program": "prog_00lhuAJjQgdtNt5WnqTBc95", "submission": "sub_14XA4WGiSOmaVI3B4QLm4Fs" }
}

Some steps happen on a hosted page: a platform sign-in, payout setup or a card. Send the person to the URL from POST /v1/connections, then wait for connection.connected or creator.payouts_updated.

Verify the signature

Every delivery has a Lucra-Signature header: t=<seconds>,v1=<hex>, where v1 is an HMAC-SHA256 of <t>.<raw body> keyed with your signing secret. Check it against the raw request body, before parsing it, and reject old timestamps:

import { createHmac, timingSafeEqual } from "node:crypto"

export function verifyLucraWebhook(
  body: string,
  header: string,
  secret: string
) {
  const { t, v1 } = Object.fromEntries(
    header.split(",").map((part) => part.split("="))
  )
  if (Math.abs(Date.now() / 1000 - Number(t)) > 300) return false
  const expected = createHmac("sha256", secret)
    .update(`${t}.${body}`)
    .digest("hex")
  return (
    v1?.length === expected.length &&
    timingSafeEqual(Buffer.from(v1), Buffer.from(expected))
  )
}

Retries

Answer with a 2xx within 10 seconds; do slow work after you respond. Failed deliveries retry for 3 days. Events can repeat or arrive out of order, so deduplicate on id.