fix: update Twilio guide

docs/integrations/twilio/webhooks.mdx

@@ -2,123 +2,155 @@
 description: Develop and test Twilio webhooks from localhost
 ---
 
-# Twilio SMS Webhooks
+# Twilio Webhooks
+
+---
 
 :::tip TL;DR
 
 To integrate Twilio webhooks with ngrok:
 
-1. [Start your local twillio webhook app.](#start-your-app) `npm start`
-1. [Start ngrok.](#start-ngrok) `ngrok http 3000`
-1. [Configure Twilio with your ngrok url and start testing.](#setup-twilio)
+1. [Launch your local webhook.](#start-your-app) `npm start`
+1. [Launch ngrok.](#start-ngrok) `ngrok http 3000`
+1. [Configure Twilio webhooks with your ngrok URL.](#setup-webhook)
+1. [Secure your webhook requests with verification.](#security)
 
 :::
 
-This guide covers how to use ngrok to integrate your localhost app with [Twilio SMS Webhooks](https://www.twilio.com/docs/usage/webhooks/sms-webhooks). By integrating ngrok with Twilio, you can:
+This guide covers how to use ngrok to integrate your localhost app with Twilio by using Webhooks.
+Twilio webhooks can be used to notify an external application whenever specific events occur in your Twilio account.
+
+By integrating ngrok with Twilio, you can:
 
-- **Develop and test Twilio webhooks locally**, eliminating the time in deploying your development code to a public environment
-- **Secure your app by validating Twilio webhook using ngrok**, letting ngrok handle security leaving more time for developing what really matters
-- **Inspect and troubleshoot requests from Twilio** in real-time via the inspection UI and API
-- **Modify and Replay Twilio Webhook requests** with a single click and without spending time reproducing events manually in Twilio
+- **Develop and test Twilio webhooks locally**, eliminating the time in deploying your development code to a public environment and setting it up in HTTPS.
+- **Inspect and troubleshoot requests from Twilio** in real-time via the inspection UI and API.
+- **Modify and Replay Twilio Webhook requests** with a single click and without spending time reproducing events manually in your Twilio account.
+- **Secure your app with Twilio validation provided by ngrok**. Invalid requests are blocked by ngrok before reaching your app.
 
 ## **Step 1**: Start your app {#start-your-app}
 
-An example express app can be found on GitHub here: [https://github.com/thomas-ngrok/ngrok-example-twilio-sms-webhook](https://github.com/thomas-ngrok/ngrok-example-twilio-sms-webhook).
+For this tutorial, we'll use the [sample NodeJS app available on GitHub](https://github.com/ngrok/ngrok-webhook-nodejs-sample).
 
-```js
-var MessagingResponse = require("twilio").twiml.MessagingResponse;
+To install this sample, run the following commands in a terminal:
 
-/*** POST /sms listing. ***/
-router.post("/", function (req, res, next) {
-	const twiml = new MessagingResponse();
-	twiml.message("The Robots are coming! Head for the hills!");
-	res.writeHead(200, { "Content-Type": "text/xml" });
-	res.end(twiml.toString());
-});
+```bash
+git clone https://github.com/ngrok/ngrok-webhook-nodejs-sample.git
+cd ngrok-webhook-nodejs-sample
+npm install
 ```
 
-Start your app on port 3000. You can validate it is up and running by visiting [http://localhost:3000](http://localhost:3000).
+This will get the project installed locally.
 
-The part we are going to focus on is http://localhost:3000/sms found under /routes/sms.js in the Express example code.
+Now you can launch the app by running the following command:
 
-More information on using Twilio webhooks can be found here: [https://www.twilio.com/blog/parsing-an-incoming-twilio-sms-webhook-with-node-js](https://www.twilio.com/blog/parsing-an-incoming-twilio-sms-webhook-with-node-js)
+```bash
+npm start
+```
+
+The app runs by default on port `3000`.
+
+You can validate that the app is up and running by visiting `http://localhost:3000`. The application logs request headers and body in the terminal and responds with a message in the browser.
 
 ## **Step 2**: Launch ngrok {#start-ngrok}
 
 Once your app is running successfully on localhost, let's get it on the internet securely using ngrok!
 
-1. If you're not an ngrok user yet, just [sign up to ngrok for free](https://ngrok.com/signup).
+1. If you're not an ngrok user yet, just [sign up for ngrok for free](https://ngrok.com/signup).
 
-2. [Download the ngrok agent](https://ngrok.com/download).
+1. [Download the ngrok agent](https://ngrok.com/download).
 
-3. Go to the [ngrok dashboard](https://dashboard.ngrok.com) and copy your Authtoken. <br />
+1. Go to the [ngrok dashboard](https://dashboard.ngrok.com) and copy your Authtoken. <br />
    **Tip:** The ngrok agent uses the authtoken to log into your account when you start a tunnel.
-4. Start ngrok by running the following command:
+1. Start ngrok by running the following command:
 
    ```bash
    ngrok http 3000
    ```
 
-5. ngrok will display a url where your example applicaiton is exposed to the internet (copy this URL for use with Twilio).
-   ![ngrok agent running](img/launch_ngrok_tunnel.png)
+1. ngrok will display a URL where your localhost application is exposed to the internet (copy this URL for use with Twilio).
+   ![ngrok agent running](/img/integrations/launch_ngrok_tunnel.png)
 
 ## **Step 3**: Integrate Twilio SMS Webhook {#setup-twilio}
 
-Now that you have your local environment on the internet, let's configure Twilio to call your code.
+## **Step 3**: Integrate Twilio {#setup-webhook}
 
-1. Sign in to your Twilio account.
-2. From the Twilio Console, go to **Develop** > **# Phone Numbers** > **Manage** > **Active Numbers** and select a number to add a webhook to.
-3. At the bottom of the page, under Messaging, (1) add your ngrok url (don't forget to append /sms) under Webhook and (2) change the type to HTTP Post.
-   ![Twilio SMS Webhook Config Screen](img/add_ngrok_url_to_Twilio.png)
-4. Save the phone number configuration.
+To register a webhook on your Twilio account follow the instructions below:
 
-Congrats, everything is configured! Now it's time to test.
+1. Access the [Twilio Console](https://console.twilio.com/) and sign in using your Twilio account.
 
-### Run Webhooks with Twilio and ngrok
+1. On the left menu, click **Develop**, click **# Phone Numbers**, click **Manage**, click **Active Numbers**, and then click your phone number.
+   **Note**: If you don't have a phone number you need to buy one by clicking **Buy a number** and following the instructions that appear in the screen.
 
-1. Send an SMS message to your Twilio Phone number that was configured in the steps above.
-2. Get excited (and maybe a little scared) when you get a text back saying, **"The Robots are coming! Head for the hills!"**
+1. On the your phone page, scroll down to the **Messaging** section and replace the URL in the **A MESSAGE COMES IN** field with the URL provided by the ngrok agent to expose your application to the internet (i.e. `https://1a2b-3c4d-5e6f-7g8h-9i0j.sa.ngrok.io`).
+   ![Twilio URL to Publish](img/ngrok_url_configuration_twilio.png)
 
-Congrats! You got an end-to-end example working but there's even more you can do with ngrok that will make development even easier. Check out how to inspect and replay your requests without having to send an SMS. Trust me, you won't regret it.
+1. Click **Save**.
 
-## Optional next steps {#optional}
+1. Select your team for the **TEAM** field, click the **created** checkbox for **Projects** under the **EVENTS** section, and then click **Submit**.
 
-### Add additional security using ngrok's signature webhook verification
+### Run Webhooks with Twilio and ngrok
 
-The webhook verification module allows ngrok to assert requests to your endpoint originate from Twillio. This is a quick step to add extra protection to your setup.
+Twilio sends different request body contents depending on the event that is being triggered.
+You can trigger new calls from Twilio to your application by following the instructions below.
 
-**Note:** This ngrok feature is limited to 500 validations per month on free ngrok accounts. For unlimited, upgrade to Pro or Enterprise.
+1. Send an SMS message to the Twilio Phone number that you configured in the previous steps.
 
-1. Login to [Twilio Console](https://console.twilio.com/) and copy your Auth Token value.<br />
-   **Note:** ngrok Webhook Verification ensures traffic from your Twilio account is the **only traffic allowed** to make calls to your app. Because Twilio signs all Webhooks using the Primary Auth Token, ngrok can verifies the signature of every request and only authorizing requests originating from your Twilio account.
-2. Restart ngrok by running the command, replacing \{your auth token\} with your Twilio Auth Token:
+   Confirm your localhost app receives a notification and logs both headers and body in the terminal.
 
-```bash
-   ngrok http 3000 --verify-webhook twilio --verify-webhook-secret {your auth token}
-```
+Optionally, you can verify the log of the webhook call in Twilio:
+
+1. On the your phone page, click the **Messages Log** tab, select **Incoming** in the **Direction** field, and then click **Filter**.
+   ![Webhook Logs](img/ngrok_logs_twilio.png)
 
 ### Inspecting requests
 
-When you launch ngrok, you can see two links: One for the tunnel to your app (it ends up with an ngrok domain unless you're using custom domains) and a local URL (http://localhost:4040) for the Request Inspector.
+When you launch the ngrok agent on your local machine, you can see two links:
 
-The Request Inspector shows all the requests made through your tunnel. When you click a request, you can see details of both requests and responses.
+- The URL to your app (it ends with `ngrok-free.app` for free accounts or `ngrok.app` for paid accounts when not using custom domains)
+- A local URL for the Web Interface (a.k.a **Request Inspector**).
 
-Seeing requests are an excellent way for validating the data sent to and retrieved by your app via the ngrok tunnel. That alone can save you some time dissecting and logging HTTP request and response headers, methods, bodies, and response codes within your app just to confirm you are getting what you expect.
+The Request Inspector shows all the requests made through your ngrok tunnel to your localhost app. When you click on a request, you can see details of both the request and the response.
 
-To inspect the Twilio SMS Webhook request, launch the ngrok inspection interface (`http://localhost:4040`), and then click the request sent by Twilio.
+Seeing requests is an excellent way of validating the data sent to and retrieved by your app via the ngrok tunnel. That alone can save you some time dissecting and logging HTTP request and response headers, methods, bodies, and response codes within your app just to confirm you are getting what you expect.
+
+To inspect Twilio's webhooks call, launch the ngrok web interface (i.e. `http://127.0.0.1:4040`), and then click one of the requests sent by Twilio.
 
 From the results, review the response body, header, and other details:
 
-![ngrok agent introspection](img/ngrok_introspection_twilio_sms_webhooks.png)
+![ngrok Request Inspector](img/ngrok_introspection_twilio_webhooks.png)
 
 ### Replaying requests
 
-The ngrok inspection interface provides a replay function that you can use to test your code without having to send an SMS to your Twilio number andthen waiting for Twilio to call your Webhook. You can even modify the replays to change the message to whatever message you are expecting.
+The ngrok Request Inspector provides a replay function that you can use to test your code without the need to trigger new events from Twilio. To replay a request:
+
+1. In the ngrok inspection interface (i.e. `http://localhost:4040`), select a request from Twilio.
 
-To replay your call:
+1. Click **Replay** to execute the same request to your application or select **Replay with modifications** to modify the content of the original request before sending the request.
+
+1. If you choose to **Replay with modifications**, you can modify any content from the original request. For example, you can modify the **id** field inside the body of the request.
 
-1. In the ngrok inspection interface (`http://localhost:4040`), select an Webhook Call from Twilio.
-1. Click **Replay** > **Replay with modifications:**
-1. Optionally, modify the request body with a different content. For example: `Body=Hello+from+the+replay+at+ngrok%21`
 1. Click **Replay**.
-1. Your local application receives the modified request to process and provide a response.
+
+Verify that your local application receives the request and logs the corresponding information to the terminal.
+
+## Secure webhook requests {#security}
+
+The ngrok signature webhook verification feature allows ngrok to assert that requests from your Twilio webhook are the only traffic allowed to make calls to your localhost app.
+
+**Note:** This ngrok feature is limited to 500 validations per month on free ngrok accounts. For unlimited, upgrade to Pro or Enterprise.
+
+This is a quick step to add extra protection to your application.
+
+1. Access the [Twilio Console](https://console.twilio.com/) and sign in using your Twilio account.
+
+1. On the console home page, copy the value of the **Auth Token** field.
+
+1. Restart your ngrok agent by running the command, replacing `{your auth token}` with the value you have copied before:
+
+   ```bash
+   ngrok http 3000 --verify-webhook twilio --verify-webhook-secret {your auth token}
+   ```
+
+1. Send an SMS message to the Twilio Phone number that you configured in the previous steps.
+
+Verify that your local application receives the request and logs information to the terminal.