The Password Problem
Before OAuth, sharing access to your API was crude. If you wanted a third-party app to post tweets on your behalf, you gave it your Twitter password. The app had full access to your account, forever, with no way to revoke it without changing your password. Every API integration that involved user data had this same problem: there was no way to grant limited, revocable access.
OAuth 1.0: Delegated Authorization
OAuth 1.0 was published in 2007 as a joint effort by Twitter, Google, and Ma.gnolia developers. The core idea: instead of sharing your password, you authorize an application to receive a token that represents specific permissions. The token could be scoped (read-only vs read-write), time-limited, and individually revocable. Your actual credentials never left your control.
OAuth 1.0 required request signing using HMAC-SHA1 and a shared secret. Every request needed a signature computed from the URL, parameters, timestamp, and nonce. This was secure but painful to implement. Libraries existed, but getting the signature calculation right without a library was a multi-hour exercise. The complexity was the cost of the security.
Webhooks: APIs That Call You Back
Jeff Lindsay introduced webhooks around 2007. The concept inverted the standard API model: instead of your application polling an API every few seconds to check for new data, the API calls your application when something happens. You register a URL. The service POSTs event data to it when the event occurs. You receive instant notification with zero polling overhead.
Webhooks replaced millions of daily polling requests with event-driven notifications. Stripe uses them to notify your server when a payment succeeds. GitHub uses them to trigger CI/CD pipelines on every commit. Slack uses them to let bots respond to messages. The pattern is simple enough that almost every API added webhook support once the concept was established.
Webhooks introduced a class of reliability problems that REST endpoints do not have. Your webhook handler can be down when the event fires. The sending service may retry with exponential backoff - or may not retry at all. Every webhook integration needs idempotency (handle duplicate deliveries gracefully) and a reconciliation mechanism for missed events.
Twilio: API as the Product
Twilio launched in 2008 with a single proposition: call a URL, send an SMS. No carrier agreements, no telecom expertise, no hardware. A developer could integrate SMS into an application in 15 minutes. This was the first time an entire telecommunications capability was delivered as a clean REST API with developer documentation that actually worked.
Twilio proved the business model of the API economy. A company whose entire product is a REST API, sold to developers by the call. Developer experience was the sales channel. The docs were the onboarding. This model - developer-first, API-first, usage-based pricing - is now the standard playbook for infrastructure companies.
Token Design Decisions That Matter in Production
OAuth tokens are not all equivalent. Opaque tokens (random strings that reference a database record) require a token introspection call for every API request to verify validity and retrieve claims. Self-contained tokens (JWTs) include claims in the token itself and can be verified locally without a database lookup. The choice affects every request in your API. Opaque tokens add a database round-trip per request but can be instantly revoked by deleting the database record. JWTs have no network overhead but cannot be truly revoked before expiry - you must wait for the token to expire or maintain a revocation list (which adds back the network overhead).
Short-lived JWTs with refresh tokens split the difference: the JWT is valid for 15 minutes (or similar), which limits the revocation window. The refresh token is long-lived and stored securely; it is used only to obtain new access tokens. This pattern is now standard for user-facing applications. The access token is JWT for fast verification. The refresh token is opaque for revocation control. Understanding this trade-off is a fundamental API security interview question.
Webhooks: Making Them Production-Ready
Registering a webhook URL is the easy part. Making webhook delivery reliable is hard. The sender must handle connection timeouts (your server might be deploying), receive timeouts (your handler is slow), and 5xx responses (your handler returned an error). The convention is exponential backoff with jitter and a maximum retry count, after which undelivered events go to a dead letter queue for manual inspection. Svix, Hookdeck, and similar webhook infrastructure services handle this so you do not have to.
Your webhook handler must be idempotent. The sending service will retry deliveries that receive no acknowledgment, even if your handler processed the event successfully before the network dropped the acknowledgment. Every event payload should include an event ID. Your handler should check this ID against a processed-event store before acting. Processing a payment webhook twice is not a theoretical edge case - it happens in any production system that handles retries.
- Scope your OAuth tokens to the minimum permissions required. A token for reading user profiles should not have write permissions.
- Include token expiry and scope in the token introspection response or JWT claims. Clients should not have to guess when to refresh.
- Webhook HMAC signatures (computing a signature of the payload with a shared secret) let your handler verify the request came from the legitimate sender.
- Webhook endpoints should return 2xx quickly and process asynchronously. Long-running webhook handlers cause delivery timeouts and retries.
- The developer experience of your webhook system is part of your API design. Clear event type names, consistent payload schemas, and a test event feature are table stakes.
The API Economy's Business Model Innovation
Twilio, Stripe, SendGrid, and Plaid proved a new business model: sell infrastructure capabilities as REST APIs, bill by usage, acquire customers through developer experience rather than sales teams. This model - sometimes called the API economy or developer-led growth - replaced the traditional enterprise software sale (pilot, proof of concept, procurement, six-month implementation). A developer trying Twilio in 2009 could have SMS working in their application in 15 minutes. A sale that used to require a VP signature was replaced by a credit card number entered into a developer console.
This shift changed how API quality is measured. Enterprise software quality was measured by features and reliability. API economy quality is measured by time-to-first-successful-call: how quickly can a developer who has never used your API get a working response? Twilio's famous 'make a phone call in 6 lines of code' demo is a product goal, not just a marketing claim. Every API in the developer-first economy is judged against this standard. Your API's quality is the time it takes a new developer to succeed.
Token Design Decisions That Matter in Production
OAuth tokens are not all equivalent. Opaque tokens (random strings that reference a database record) require a token introspection call for every API request to verify validity and retrieve claims. Self-contained tokens (JWTs) include claims in the token itself and can be verified locally without a database lookup. The choice affects every request in your API. Opaque tokens add a database round-trip per request but can be instantly revoked by deleting the database record. JWTs have no network overhead but cannot be truly revoked before expiry - you must wait for the token to expire or maintain a revocation list (which adds back the network overhead).
Short-lived JWTs with refresh tokens split the difference: the JWT is valid for 15 minutes (or similar), which limits the revocation window. The refresh token is long-lived and stored securely; it is used only to obtain new access tokens. This pattern is now standard for user-facing applications. The access token is JWT for fast verification. The refresh token is opaque for revocation control. Understanding this trade-off is a fundamental API security interview question.
Webhooks: Making Them Production-Ready
Registering a webhook URL is the easy part. Making webhook delivery reliable is hard. The sender must handle connection timeouts (your server might be deploying), receive timeouts (your handler is slow), and 5xx responses (your handler returned an error). The convention is exponential backoff with jitter and a maximum retry count, after which undelivered events go to a dead letter queue for manual inspection. Svix, Hookdeck, and similar webhook infrastructure services handle this so you do not have to.
Your webhook handler must be idempotent. The sending service will retry deliveries that receive no acknowledgment, even if your handler processed the event successfully before the network dropped the acknowledgment. Every event payload should include an event ID. Your handler should check this ID against a processed-event store before acting. Processing a payment webhook twice is not a theoretical edge case - it happens in any production system that handles retries.
- Scope your OAuth tokens to the minimum permissions required. A token for reading user profiles should not have write permissions.
- Include token expiry and scope in the token introspection response or JWT claims. Clients should not have to guess when to refresh.
- Webhook HMAC signatures (computing a signature of the payload with a shared secret) let your handler verify the request came from the legitimate sender.
- Webhook endpoints should return 2xx quickly and process asynchronously. Long-running webhook handlers cause delivery timeouts and retries.
- The developer experience of your webhook system is part of your API design. Clear event type names, consistent payload schemas, and a test event feature are table stakes.
The API Economy's Business Model Innovation
Twilio, Stripe, SendGrid, and Plaid proved a new business model: sell infrastructure capabilities as REST APIs, bill by usage, acquire customers through developer experience rather than sales teams. This model - sometimes called the API economy or developer-led growth - replaced the traditional enterprise software sale (pilot, proof of concept, procurement, six-month implementation). A developer trying Twilio in 2009 could have SMS working in their application in 15 minutes. A sale that used to require a VP signature was replaced by a credit card number entered into a developer console.
This shift changed how API quality is measured. Enterprise software quality was measured by features and reliability. API economy quality is measured by time-to-first-successful-call: how quickly can a developer who has never used your API get a working response? Twilio's famous 'make a phone call in 6 lines of code' demo is a product goal, not just a marketing claim. Every API in the developer-first economy is judged against this standard. Your API's quality is the time it takes a new developer to succeed.
Token Design Decisions That Matter in Production
OAuth tokens are not all equivalent. Opaque tokens (random strings that reference a database record) require a token introspection call for every API request to verify validity and retrieve claims. Self-contained tokens (JWTs) include claims in the token itself and can be verified locally without a database lookup. The choice affects every request in your API. Opaque tokens add a database round-trip per request but can be instantly revoked by deleting the database record. JWTs have no network overhead but cannot be truly revoked before expiry - you must wait for the token to expire or maintain a revocation list (which adds back the network overhead).
Short-lived JWTs with refresh tokens split the difference: the JWT is valid for 15 minutes (or similar), which limits the revocation window. The refresh token is long-lived and stored securely; it is used only to obtain new access tokens. This pattern is now standard for user-facing applications. The access token is JWT for fast verification. The refresh token is opaque for revocation control. Understanding this trade-off is a fundamental API security interview question.
Webhooks: Making Them Production-Ready
Registering a webhook URL is the easy part. Making webhook delivery reliable is hard. The sender must handle connection timeouts (your server might be deploying), receive timeouts (your handler is slow), and 5xx responses (your handler returned an error). The convention is exponential backoff with jitter and a maximum retry count, after which undelivered events go to a dead letter queue for manual inspection. Svix, Hookdeck, and similar webhook infrastructure services handle this so you do not have to.
Your webhook handler must be idempotent. The sending service will retry deliveries that receive no acknowledgment, even if your handler processed the event successfully before the network dropped the acknowledgment. Every event payload should include an event ID. Your handler should check this ID against a processed-event store before acting. Processing a payment webhook twice is not a theoretical edge case - it happens in any production system that handles retries.
- Scope your OAuth tokens to the minimum permissions required. A token for reading user profiles should not have write permissions.
- Include token expiry and scope in the token introspection response or JWT claims. Clients should not have to guess when to refresh.
- Webhook HMAC signatures (computing a signature of the payload with a shared secret) let your handler verify the request came from the legitimate sender.
- Webhook endpoints should return 2xx quickly and process asynchronously. Long-running webhook handlers cause delivery timeouts and retries.
- The developer experience of your webhook system is part of your API design. Clear event type names, consistent payload schemas, and a test event feature are table stakes.
The API Economy's Business Model Innovation
Twilio, Stripe, SendGrid, and Plaid proved a new business model: sell infrastructure capabilities as REST APIs, bill by usage, acquire customers through developer experience rather than sales teams. This model - sometimes called the API economy or developer-led growth - replaced the traditional enterprise software sale (pilot, proof of concept, procurement, six-month implementation). A developer trying Twilio in 2009 could have SMS working in their application in 15 minutes. A sale that used to require a VP signature was replaced by a credit card number entered into a developer console.
This shift changed how API quality is measured. Enterprise software quality was measured by features and reliability. API economy quality is measured by time-to-first-successful-call: how quickly can a developer who has never used your API get a working response? Twilio's famous 'make a phone call in 6 lines of code' demo is a product goal, not just a marketing claim. Every API in the developer-first economy is judged against this standard. Your API's quality is the time it takes a new developer to succeed.