Provider Catalog API
The provider catalog describes every webhook provider Hookbase knows about: how its signatures are verified, which credential a source needs and where to find it, and the event types it sends. The dashboard, CLI and MCP server build their create-source flows from it, and you can too.
The catalog is public. No API key is needed.
Endpoints
| Method | Path | Description |
|---|---|---|
| GET | /api/catalog/providers | List providers |
| GET | /api/catalog/providers/{providerId} | Get one provider in full |
| GET | /api/catalog/providers/{providerId}/events | Get a provider's event types and sample payloads |
Info
A catalog id is not always the source provider value. Use the entry's hookbaseProvider
when creating a source. For example the catalog entry mollie-nextgen maps to the mollie
provider, and a few entries Hookbase can't verify yet map to custom.
List Providers
GET /api/catalog/providersQuery Parameters
| Parameter | Type | Description |
|---|---|---|
| category | string | Only providers in this category, e.g. payments (one of categories in the response) |
| search | string | Case-insensitive match against name, description and category |
Example
curl "https://api.hookbase.app/api/catalog/providers?category=payments"Response
{
"providers": [
{
"id": "stripe",
"name": "Stripe",
"category": "payments",
"description": "Payment processing platform. Receive events for charges, subscriptions, invoices, disputes, and payouts.",
"icon": "💳",
"eventTypeCount": 10,
"hookbaseProvider": "stripe",
"hasSignatureVerification": true,
"hasIpRanges": true,
"signatureVerification": {
"supported": true,
"kind": "hmac",
"secretSource": "provider",
"secretLabel": "Signing secret",
"secretPlaceholder": "whsec_..."
}
}
],
"categories": ["analytics", "auth", "communication", "crm", "developer-tools", "e-commerce", "email", "fintech", "forms", "infrastructure", "monitoring", "payments", "productivity"],
"total": 1
}Each list item carries a signatureVerification summary — enough to label a secret field and decide
whether to ask for one. If you are talking to
an API version whose list items lack the key, read the same fields from
Get Provider.
Get Provider
GET /api/catalog/providers/{providerId}Returns the whole catalog entry: website, docsUrl, ipRanges, eventTypes, samplePayloads,
setupGuide (ordered setup steps) and the full signatureVerification block.
Example
curl https://api.hookbase.app/api/catalog/providers/whatsappResponse
{
"provider": {
"id": "whatsapp",
"name": "WhatsApp Business",
"category": "communication",
"description": "Meta WhatsApp Business API. Receive events for messages, message status updates, and template updates.",
"website": "https://business.whatsapp.com",
"docsUrl": "https://developers.facebook.com/docs/graph-api/webhooks/getting-started",
"icon": "📱",
"hookbaseProvider": "whatsapp",
"signatureVerification": {
"supported": true,
"algorithm": "HMAC-SHA256",
"headerName": "X-Hub-Signature-256",
"secretLocationHint": "Meta App Dashboard → Your App → App settings → Basic → App secret (click Show)...",
"secretLabel": "App secret",
"secretSource": "provider",
"secretInstruction": "Copy the App secret from App settings → Basic in your Meta App Dashboard (click Show) and paste it here.",
"verifyToken": {
"label": "Verify token",
"instruction": "Hookbase generates this. Paste it into the Verify token field next to the Callback URL under WhatsApp → Configuration → Webhook."
},
"kind": "hmac"
},
"eventTypes": [
{ "type": "messages", "description": "A new message was received" }
],
"samplePayloads": { "messages": { "object": "whatsapp_business_account", "entry": [] } },
"ipRanges": null,
"setupGuide": [
"In the Meta App Dashboard, open App settings → Basic and copy the App secret (click Show)",
"Paste the App secret into this Hookbase source"
]
}
}Returns 404 with {"error": "Provider not found"} for an unknown providerId.
Get Provider Events
GET /api/catalog/providers/{providerId}/eventsExample
curl https://api.hookbase.app/api/catalog/providers/stripe/eventsResponse
{
"providerId": "stripe",
"providerName": "Stripe",
"eventTypes": [
{ "type": "charge.succeeded", "description": "A charge was successfully completed" },
{ "type": "charge.failed", "description": "A charge attempt failed" }
],
"samplePayloads": {
"charge.succeeded": { "id": "evt_...", "type": "charge.succeeded", "data": { "object": {} } }
}
}404 for an unknown providerId.
Signature Verification Fields
| Field | In list | Description |
|---|---|---|
| supported | Yes | Hookbase verifies this provider's signatures |
| kind | Yes | Verification family: hmac (keyed hash over a signing string), shared_secret (a token or Basic-auth value compared as-is), bespoke (provider-specific scheme, e.g. Square signs the URL plus body, AWS SNS uses a certificate) or asymmetric (vendor's public key). Absent for entries that map to custom |
| secretSource | Yes | Who produces the credential — see below |
| secretLabel | Yes | The vendor's own name for the credential ("Signing secret", "App secret", "Public key"…). Use it to label the input |
| secretPlaceholder | Yes | Optional input placeholder, e.g. whsec_... |
| secretAfterRegistration | Yes | Present and true when the vendor issues the secret only after the ingest URL is registered with it (asana, notion). Create the source without one |
| algorithm | Detail only | Human-readable algorithm, e.g. HMAC-SHA256 |
| headerName | Detail only | Header the signature arrives in |
| secretLocationHint | Detail only | Where in the vendor's UI the credential lives |
| secretInstruction | Detail only | One sentence telling the user where to copy the value from, where to paste a generated one, or why there is nothing to enter |
| secretFormat | Detail only | Extra shape rule: whsec (whsec_ + base64, never generated) or basic_auth (the vendor sends HTTP Basic auth; Hookbase generates and stores base64(username:password)) |
| verifyToken | Detail only | Present for Meta providers (whatsapp): {label, instruction} for the second, Hookbase-generated credential Meta checks at registration. See Get Verify Token |
secretSource values
| Value | Meaning | When creating a source |
|---|---|---|
provider | The vendor issues the secret | Paste it as signingSecret. Some providers (Standard Webhooks whsec_ keys, airtable, gitlab-signing-token, supabase-auth-hooks) return 400 without it |
operator | The vendor has a field you type a secret into but never issues one | Omit signingSecret; Hookbase generates one and returns it once. Paste it into the vendor |
public_key | The vendor's public verification key | Paste the PEM/base64 key as signingSecret; 400 without it |
built_in | The vendor publishes one key or certificate for everyone and Hookbase already has it | Send no signingSecret (sending one is a 400). Events are still verified; the source reports verifiesWithoutSecret: true |
none | The vendor doesn't sign, or Hookbase can't verify its scheme yet | Nothing needed; the source verifies as custom |
See Signing secrets by provider for how
these rules apply to POST /api/sources and rotate-secret.