1 min lesson
Inbound webhooks and API drift
Use "Pagination, the secondary rate limit, signature verification, API drift" to describe the practical rule.
Step 1 of 2
Inbound webhooks and API driftthe integration is two-directional
Providers also push events to you - PR opened, push, comment. Treat that ingress like any untrusted, at-least-once stream: verify the signature, dedupe on the delivery id and tolerate replays and out-of-order arrival. Separately, providers change their APIs without asking. The adapter layer is the firewall that absorbs that churn so no product team has to.
Don't promise "exactly-once" webhook processing - providers deliver at-least-once and will redeliver. The honest answer is idempotent handlers keyed on the delivery id, so a duplicate is a no-op. Claiming exactly-once at the network boundary is a tell that you haven't run one of these in production.
"I'd put one provider-neutral interface in front of GitHub, GitLab and Bitbucket and push every quirk - pagination, the secondary rate limit, signature verification, API drift - down into per-provider adapters. Product surfaces get a stable contract; when GitHub changes an endpoint or has an outage, I change one adapter and degrade gracefully and nobody else's code moves."