Webhooks let HubSpot tell your app when something changed — deal stage, contact property, ticket update — without polling. They’re powerful and easy to get wrong. This primer is the minimum production checklist.
1. Know what you’re subscribing to
- Workflow webhooks — fire from a HubSpot workflow with a payload you control
- App webhooks / CRM extensions — broader event subscriptions for private apps
- Prefer the smallest event set that solves the job (deal.propertyChange beats “everything”)
- Document why each subscription exists — future you will thank you
2. Verify every request
If you don’t verify signatures, anyone who finds your URL can inject fake CRM events.
- Validate HubSpot’s signature / v3 request signature on every POST
- Reject requests with stale timestamps (replay protection)
- Use HTTPS only; rotate secrets when people leave the project
- Return 401/403 on bad signatures — don’t process “just in case”
3. Respond fast, process async
- Acknowledge with 2xx quickly (HubSpot retries on timeouts/5xx)
- Push work to a queue/worker; don’t run heavy syncs in the request thread
- Make handlers idempotent: same event ID processed twice = one effect
- Store processed event IDs (or object version) for dedupe
4. Fetch what you need
Many payloads are thin. After verify + enqueue, fetch the full object via API if you need more fields — with rate-limit awareness.
- Use private app tokens with least privilege scopes
- Backoff on 429s; never tight-loop HubSpot APIs
- Cache rarely changing reference data
- Write results back carefully — avoid webhook → write → webhook loops
5. Operate it
- Alert on spike in 4xx/5xx or queue depth
- Dead-letter failed jobs with enough payload to replay
- Staging portal + staging consumer before production cutover
- Runbook: how to pause subscriptions and drain the queue
A boring webhook pipeline — verified, queued, idempotent — is how custom tools stay honest with CRM truth.