RESTful API
design & development
in Boston

Many integrations begin with polling. A partner system asks the API every few minutes whether anything new has happened. Most of the time the answer is no. The traffic is wasted, and changes still arrive late. Webhooks reverse the direction. When something happens, the API sends a message to an address the partner has registered.

The idea is simple. The details decide whether partners can rely on it.

Each event needs a clear name and a stable format. An order created, a payment failed, a user deleted. The message should contain an identifier, the event type, a timestamp and either the relevant data or enough information to fetch it. Changing that format later breaks receivers, so it deserves the same versioning care as any other part of the API.

Delivery will fail sometimes. The receiving server may be down, slow or returning errors. The sender should retry with increasing delays, over a period long enough to cover a short outage, and then stop and record the failure. Partners need a way to see failed deliveries and trigger them again.

Retries create duplicates. A message may arrive twice because the first response was lost on the way back. Receivers must be able to recognise an event they have already processed, usually by its identifier, and ignore the repeat. The documentation should say this plainly.

Order is not promised. Two events about the same object can arrive in the wrong sequence, especially after retries. Including a version number or the time of the change lets receivers discard older information that arrives late.

Security matters because the endpoint is public. Anyone who knows the address could send fake events. Signing each message with a shared secret, and asking receivers to verify the signature, closes that gap. Timestamps inside the signed content stop old messages from being replayed.

Receivers should answer quickly. The recommended pattern is to acknowledge the message at once and process it in the background. A receiver that does heavy work before replying will time out and trigger retries it did not need.

Partners need tools for testing. A way to send sample events to a development address, and a log showing what was sent and what came back, saves many support conversations.

Finally, polling should remain possible. Webhooks can be missed. A list endpoint that returns changes since a given time lets partners reconcile and recover anything that slipped through.

Subscriptions deserve their own management screen. Partners should be able to choose which event types they receive, register several addresses, and pause delivery while they fix a problem on their side. When an address keeps failing for days, the sender should disable it and notify the partner, instead of retrying forever against a server that no longer exists.

Payload size is worth deciding early. Some teams send the full object with every event. Others send only the identifier and let the receiver fetch the current state. Full payloads are convenient but can leak data to endpoints that do not need it. Thin payloads keep messages small and always return fresh data.

A public list of event types, with an example message for each and the date it was introduced, gives partners a clear contract to build against and makes later changes easier to announce.