Connecting a source
Every connector is one credential and one API call. This page is the whole of it: which credential each provider needs, where to create it, what HookGet does with it, and what to look at when something fails.
In short
- Push sources: we give you a secret (or you paste the provider’s public key), you paste it into their webhook settings. Done.
- Pull sources: you paste one credential — an access token or a service-account JSON key — and choose an interval. The first sync runs immediately.
- Credentials are encrypted at rest, used only at sync time, and returned by no route.
- Health is per source, in words:
auth_failed,rate_limited,ok: 41 new, 3 already seen. - Everything here is one
POST /v1/sources— no OAuth redirect flows, no browser dance.
The credential, provider by provider
| Provider | What you paste | Where you get it | Scope it needs |
|---|---|---|---|
| Stripe | nothing — we generate the secret | paste ours into Stripe → Webhooks | the events you select in Stripe |
| SendGrid | their verification key (public) | Settings → Mail Settings → Event Webhook | — |
| GoHighLevel | their public key (PEM) | GHL developer docs | — |
| Postmark | nothing — we generate the token | paste as basic-auth password on the webhook | — |
| n8n | nothing — we generate the token | add as a header on your HTTP Request node | — |
| OpenAI | an organization admin key | OpenAI console → organization settings | usage + costs (read) |
| Anthropic | an Admin API key | Anthropic console | usage + cost reports (read) |
| Google Analytics 4 | a service-account JSON key | Google Cloud console | Viewer on the GA4 property |
| Search Console | the same JSON key works | Google Cloud console | user on the Search Console property |
| Meta Ads | a system-user access token | Business settings → System users | ads_read |
| TikTok Ads | an access token | Ads Manager → API access | reporting (read) |
When something fails
| You see | It means | What to do |
|---|---|---|
auth_failed health | the provider rejected the credential | create a fresh one, update the source, resume — the cursor is kept |
rate_limited health | the provider throttled us | nothing — the sync backs off exactly as long as the provider asked |
| a paused source you did not pause | 20 consecutive failures | fix the credential, resume; the failure count and backoff reset |
401 on /ingest/… in provider logs | their signature did not verify | usually a rotated secret — rotate on our side too; both verify during the overlap |
| events with the provider’s own names | the source predates canonical naming, or the type is unmapped | expected — nothing is dropped; see the source page for the mapping |
Questions
Where do credentials live, and who can read them back?
Every credential — generated secret, access token, service-account key — is encrypted with AES-256-GCM before it touches the database, is decrypted only at the moment of use, and is returned by no API route. A generated secret is shown exactly once, at creation. Lost one? Rotate: the new secret is issued and the old keeps verifying until the overlap window closes, so rotation is never an outage.
What does source health actually tell me?
A machine-stable code and a human sentence: auth_failed: meta: Error validating
access token, rate_limited, unreachable. It is set by every
sync, visible on the source, and honest — a source that has failed twenty syncs in a row
pauses itself and says so, rather than pretending to be connected.
Can a connector see data from another project?
No, structurally. The project an event lands in comes from the source row itself — never from anything in a payload or a provider response. The envelope builder refuses tenant-shaped fields in event attributes outright, and the isolation suite tries the cross-tenant paths on every build.
What happens on my side when I revoke a credential at the provider?
The next sync fails with auth_failed, the source backs off and then
pauses. Nothing retries forever. When you paste a new credential and resume, the failure
count clears and reading continues from the saved cursor — no gap, no duplicates.
Do I need a separate HookGet plan for sources?
No. Source events meter exactly like published events — the 64KB unit rule, counted at fan-out — and appear in the same usage view. A source with no subscribed destination stores events but fans out to nobody, and a delivery that did not happen is not billed.