Skip to content
Tutorials Center
My learning

Topics

Lesson 33 of 37 ยท Integrations and API

Webhooks, Rate Limits and Reliable Integrations

Learn how HubSpot webhooks notify your server, how to verify request signatures, handle retries idempotently, and respect rate limits with backoff, using runnable Python stand-ins.

Polling an API every minute to ask "did anything change?" wastes requests. Webhooks reverse the flow: HubSpot sends an HTTP POST to your server when something happens, such as a contact being created or a deal stage changing. Reliable integrations also respect rate limits, verify who is calling them, and survive duplicate or out-of-order deliveries.

HubSpot cannot send webhooks to this page. The runnable blocks are Python stand-ins that implement the checks yourself. Subscription setup, limits and header names are summarized from HubSpot's developer documentation and can change, so confirm in the current docs.

Two kinds of webhooks

  • Webhook subscriptions in a public or legacy app: you subscribe to events such as contact.creation, contact.propertyChange, deal.propertyChange and ticket.creation; HubSpot batches events into arrays and POSTs them to your target URL.
  • Workflow webhook action: a workflow step (Professional or higher) POSTs the enrolled record's properties to a URL. Use this for simple "tell my system" notifications.

A subscription delivery is a JSON array, for example:

JSON
[
  { "eventId": 100, "subscriptionType": "deal.propertyChange", "objectId": 555,
    "propertyName": "dealstage", "propertyValue": "closedwon", "occurredAt": 1767225600000 }
]

Your endpoint should return a 2xx status quickly (within a few seconds), then do heavy work asynchronously. If it times out or returns an error, HubSpot retries several times over many hours.

Safe webhook handler

Verify signature Reject forged requests
Check timestamp Reject replays
Deduplicate Same event may arrive twice
Reply fast Queue work, return 200

Assume retries and disorder

1 / 2

Verifying the signature

HubSpot signs requests so you can tell they came from HubSpot. With the v3 signature, it sends X-HubSpot-Signature-v3 and X-HubSpot-Request-Timestamp. You compute an HMAC-SHA256 of the string method + url + body + timestamp with your app's client secret, base64-encode it, and compare in constant time. Reject timestamps older than five minutes. (Check the docs for exact URL-decoding rules for the string.)

Python Verify a v3-style signature (stand-in)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Idempotent handling

Retries mean the same event can arrive more than once, and events can arrive out of order. Handle this by recording processed eventId values and by comparing occurredAt before overwriting data.

Python Deduplicate and ignore stale events

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Rate limits

HubSpot limits how fast an account can call the API. Private apps have a burst limit per ten seconds and a daily limit that depend on the account's subscription (documented in the developer docs; the burst limit is in the low hundreds of requests per ten seconds). The search API has a much lower per-second limit. When you exceed a limit the API returns 429 Too Many Requests with a message and, usually, response headers describing your remaining quota (for example X-HubSpot-RateLimit-Remaining).

The right reaction is exponential backoff with jitter: wait, retry, wait longer.

Python Backoff on 429 (simulated server)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Staying inside the limits

  • Use batch endpoints and the search filters instead of many small calls (API lesson).
  • Cache lookups such as owner lists and property definitions.
  • Subscribe to webhooks instead of polling.
  • Spread bulk jobs over time with a queue that limits concurrency.
  • Never loop forever on a failing call; cap attempts and alert.
Python A token-bucket limiter

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Check your understanding

Quick check ยท 3 questions

of 3 answered You scored / 3 ยท perfect!

  1. 1. Why verify the webhook signature?

    Anyone can POST to a public URL; the HMAC proves authenticity.
  2. 2. Webhooks can deliver the same event twice. What do you do?

    Idempotent handlers store processed IDs and ignore repeats.
  3. 3. What should you do after a 429 response?

    Backoff gives the limit window time to recover and avoids thundering herds.

Summary

  • Webhooks push events to your server; verify signatures and timestamps.
  • Handle retries and out-of-order delivery with idempotency.
  • Respect rate limits: batch, cache, queue and back off on 429.

Next: Custom Properties, Objects and Associations