Webhooks

Lucra POSTs an event to your server when something changes, so you don't have to poll.

Set up

Add a webhook URL when you create a key, or have the key set its own with PATCH /v1/keys/current ({ "webhookUrl": "https://…" }; null stops events). Lucra shows a signing secret (whsec_…) once; setting a URL again issues a new one. GET /v1/keys/current reads the URL.

Who hears an event

A key hears events about its own account and, for a partner, the brands it reaches. A partner key also hears every event about a creator active on its roster (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 what was sent to the key's webhook, newest first, with each one's delivery status. It has only events from while the key had a webhook URL.

Events

Events name what changed and the IDs involved; fetch the details from the API. Events about a creator also carry creator. Ignore types you don't handle.

To finish a hosted step a creator or brand has to take, send them to the URL from POST /v1/connections (a platform sign-in, payout setup or a card), then wait for creator.payouts_updated or connection.connected.

{
  "id": "evt_u5s9xZIdD99WBwmDjJPYc3e",
  "type": "submission.approved",
  "account": "acct_04Jm0JWUg20EhYo2lyNIEHo",
  "data": { "submission": "sub_14XA4WGiSOmaVI3B4QLm4Fs" }
}

Verify the signature

Lucra-Signature: t=<seconds>,v1=<hex> is an HMAC-SHA256 of <t>.<raw body> with your secret.

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 2xx within 10 seconds. Failed deliveries retry for 3 days. Events can repeat or arrive out of order, so deduplicate on id.