Concepts
Four objects show up in every integration:
- Workspace — the container everything else lives in. Your forms, leads, and credentials all belong to exactly one workspace.
- Form — a named, workspace-scoped definition of the fields you're submitting (
name,email,company, …). Every form has a unique slug, and optionally a webhook secret for signed submissions. - Lead — a single submission. Every lead is attributed to the form it came in through, scored automatically, and (for clean submissions) enriched asynchronously.
- Token / secret — the credential a given surface authenticates with. Which kind you need depends on which surface you're integrating against — see below.
Three surfaces, three threat models
Black Glass Leads exposes three ways to get a lead in, and they exist because they answer three different questions: who is sending this, and how much do we trust the channel it arrives on?
| Surface | Credential | Runs where | |
|---|---|---|---|
| 1a | Server Bearer token | Authorization: Bearer ingt_srv_… | Your backend, Zapier, Make — anywhere you can set a custom header and keep a secret server-side |
| 1b | HMAC-signed slug webhook | Per-form webhook secret, signed per-request | A webhook provider posting to a public URL it doesn't control the trust of |
| 2 | Browser SDK | Origin-bound, short-lived submission token | The browser — the one place a long-lived secret can never be safe |
Surface 1a — server Bearer tokens
The credential is a long-lived token that never leaves your server. The threat model is simple: as long as the token stays server-side, only you can submit leads with it. This is the surface to reach for first — it's the least ceremony for the most common case (your own backend, or a webhook-relay tool that supports custom headers). See the server webhooks guide.
Surface 1b — HMAC-signed slug webhooks
Some webhook providers post to a public URL that anyone who finds it could hit — there's no way to keep the URL secret, so the credential can't be "don't tell anyone the endpoint." Instead, every request is signed: a per-form secret produces an HMAC-SHA256 signature over a timestamp and the request body, and the timestamp bounds how long a captured request stays replayable. See the signed webhooks guide.
Surface 2 — browser SDK
The browser is the one place you categorically cannot keep a secret — anything shipped to the client is visible to whoever opens dev tools. This surface trades a long-lived credential for a short-lived, origin-bound submission token minted just before use, so a leaked token is worthless outside the page that requested it and expires fast even if it isn't. The browser SDK guide is coming in a later phase of this site — for now, server webhooks or signed webhooks cover every integration we support.