Webhooks and API Constraints

What it is

A webhook is an HTTP callback in which a service sends a message to your application when an event happens.

Normal API use is pull. Your code asks and the server answers.

A webhook is push. The server contacts you as soon as something changes.

When you consume any API, you also work within limits such as rate limits, page sizes and time outs. Good code expects them.

How it works

A webhook needs a registration step, a receiving endpoint and a safe way to process events.

The webhook pattern

1. You build a small web service with an endpoint that accepts POST requests.
2. You register that address with the provider and say which events you want.
3. When an event occurs, the provider sends a POST with a JSON body that describes it.
4. Your endpoint replies with a success code, normally 200, quickly.
5. Your code then acts on the event.

Webhooks avoid polling. Polling wastes calls and delays your reaction. A webhook gives near real time news with no repeated requests.

Registering a webhook

Many platforms let you register through their API. For example, Webex accepts a POST to /v1/webhooks with a body like this.

{
  "name": "New messages",
  "targetUrl": "RECEIVER_ADDRESS",
  "resource": "messages",
  "event": "created"
}

RECEIVER_ADDRESS stands for the public address of your endpoint. The provider must be able to reach it from the internet, or through a tunnel when you test on a laptop.

A simple receiver

from flask import Flask, request

app = Flask(__name__)


@app.route("/hook", methods=["POST"])
def hook():
    event = request.get_json()
    print(event)
    return "", 200

Keep the handler quick. If the work takes long, store the event and process it afterwards, so you can answer at once.

Securing a webhook

• Serve the endpoint over HTTPS.
• Many providers sign each message with a shared secret, so your code can check that the call is genuine.
• Treat the body as untrusted input, and validate it before you use it.

Constraints when consuming APIs

Pagination in practice

An API may return only part of a large list, with a way to get the next part. Some APIs give a Link header that points to the next page. Others use a limit and offset, or a cursor value.

url = BASE_URL + "/v1/devices"
params = {"limit": 100}
items = []

while url:
    response = requests.get(url, headers=headers, params=params, timeout=10)
    response.raise_for_status()
    items.extend(response.json()["items"])
    url = response.links.get("next", {}).get("url")
    params = None

The requests library parses the Link header into response.links. This pattern works only for APIs that use that header, so check the documentation for yours.

Retrying politely

When a call fails with 429 or a 5xx code, wait and try again. Doubling the wait each time is called exponential backoff. Set a maximum number of tries so the script cannot loop forever.