How products integrate APIs

A real integration, from start to finish

You've learned every building block: JSON, requests, REST, authentication, documentation, webhooks. Now let's put them all together.

Here's the scenario. You're a PM at an e-commerce company. The team wants to send an SMS confirmation when a customer places an order. Your app doesn't send text messages, so you need an external service. That service is Twilio.

Let's walk through exactly how this integration works, step by step.

Step 1: the product need

A customer places an order on your website. You want them to immediately receive a text message: "Your order #4821 has been confirmed. Estimated delivery: March 8."

Your app handles the order. But sending an SMS? That's not something you build from scratch. You use a service that specializes in it. Twilio has an API that sends text messages. Your server calls Twilio's API, Twilio delivers the SMS to the customer's phone.

This is the pattern behind most integrations. Your product focuses on what it does best (managing orders), and an external API handles the rest (sending texts).

Step 2: find the right endpoint

Your engineer goes to Twilio's API documentation and finds the endpoint for sending a message. Here's what the request looks like:

This should look familiar from Chapter 2:

• POST because you're creating something (a new message)
• The base URL is Twilio's API server
• The path points to the Messages resource under your account. It looks a bit unusual: /2010-04-01/ is a version date (Twilio's way of versioning their API), {AccountSid} is your unique account identifier, and .json at the end tells Twilio you want the response in JSON. Not every API formats its URLs this way, but the logic is the same: version, account, resource.

Step 3: authenticate

In Chapter 4, you saw API keys sent as Authorization: Bearer your_api_key. Twilio uses a slightly different method called Basic Authentication. Instead of one API key, you have two values: an Account SID (your username) and an Auth Token (your password). They get combined into a single string separated by a colon, then encoded in a format called base64.

Here's what that looks like concretely. Your two credentials:

• Account SID: AC1234567890abcdef
• Auth Token: e9f8a7b6c5d4e3f2

Get combined into AC1234567890abcdef:e9f8a7b6c5d4e3f2, then base64-encoded into QUMxMjM0NTY3ODkwYWJjZGVmOmU5ZjhhN2I2YzVkNGUzZjI=. That encoded string goes in the header:

Don't worry about the encoding itself. Your engineering team's code handles that automatically. The important thing to know: Basic Auth is just another way of sending credentials in the Authorization header. Some APIs use Bearer + a single key, others use Basic + an encoded username:password combo. The docs always tell you which one.

The body contains three fields: the recipient's phone number, your Twilio phone number, and the message text. That's all Twilio needs to send an SMS.

Step 4: get the response

Twilio processes the request and sends back a JSON response confirming the message was created:

The status: "queued" means Twilio accepted the message and will deliver it shortly. The sid is the unique identifier for this message (like an order ID, but for the SMS).

Step 5: the webhook callback

But how do you know the SMS was actually delivered? Maybe the phone number is wrong. Maybe the carrier blocked it. This is where webhooks come in (Chapter 6).

When you configured the integration, your team registered a webhook URL with Twilio. Now, when the SMS status changes, Twilio sends a POST request back to your server:

Your server receives this, sees "MessageStatus": "delivered", and knows the customer got the text. If the status were "failed", your server could flag it and maybe send an email instead.

The full picture

Every step of this integration maps to a concept you already know:

That's one integration. But this same pattern repeats everywhere: sending emails (Postmark), processing payments (Stripe), generating PDFs (DocSpring), translating text (DeepL). The service changes, but the flow is the same. Find the endpoint, authenticate, send a request, handle the response, listen for webhooks.

Key takeaways

• Most product features that rely on external services follow the same integration pattern: find the endpoint, authenticate, send a request, handle the response.
• Webhooks close the loop by notifying your server when something happens asynchronously (like an SMS being delivered or failing).
• Every step maps directly to a concept you've already learned. There's nothing new here, just all the pieces working together.