Updated the docs

Author: matt-aitken

docs/wait-for-http-callback.mdx

@@ -5,86 +5,82 @@ description: "Pause runs until an HTTP callback is made to the provided URL."
 
 import UpgradeToV4Note from "/snippets/upgrade-to-v4-note.mdx";
 
-The `wait.forHttpCallback()` function gives you a callback URL, and then pauses the run until that callback is hit with a POST request. This is most commonly used with 3rd party APIs that take a long time and that accept a callback (or webhook) URL.
+The `wait.createHttpCallback()` function gives you a callback URL and returns a token representing the waitpoint. You should call a third-party API and provide it with the callback URL so they can notify you when their work is done.
 
-When the callback URL is requested the run will continue where it left off with the body of the request as the output available for you to use.
+Then you can use `wait.forToken()` to pause the run until the callback URL is hit with a `POST` request.
 
 <UpgradeToV4Note />
 
 ## Usage
 
-In this example we create an image using Replicate. Their API accepts a "webhook", which is a callback.
+In this example we create an image using Replicate. Their API accepts a “webhook”, which is an HTTP POST callback.
 
 ```ts
 import { logger, task, wait } from "@trigger.dev/sdk";
-
-const replicate = new Replicate({
-  auth: process.env.REPLICATE_API_KEY,
-});
+import Replicate, { Prediction } from "replicate";
 
 export const replicate = task({
   id: "replicate",
   run: async () => {
-    // This will pause the run and give you a URL
-    const result = await wait.forHttpCallback<Prediction>(
+    const replicate = new Replicate({
+      auth: process.env.REPLICATE_API_KEY,
+    });
+
+    // 1️⃣ Create the callback URL and token
+    const { token, data } = await wait.createHttpCallback(
       async (url) => {
         //   👆 This URL continues your run when hit with a POST request
 
-        // Make the call to Replicate, passing in the URL
-        await replicate.predictions.create({
+        // 2️⃣ Kick off the long-running job, passing in the URL
+        return replicate.predictions.create({
           version: "27b93a2413e7f36cd83da926f3656280b2931564ff050bf9575f1fdf9bcd7478",
           input: {
             prompt: "A painting of a cat by Any Warhol",
           },
-          // Make sure to pass the callback URL
-          //       👇
-          webhook: url,
-          // We only want to call when it's completed
+          webhook: url, // 👈 pass the callback URL
           webhook_events_filter: ["completed"],
         });
       },
       {
         // We'll fail the waitpoint after 10m of inactivity
         timeout: "10m",
+        // Tags can be used to filter waitpoints in the dashboard
+        tags: ["replicate"],
       }
     );
 
-    if (!result.ok) {
+    logger.log("Create result", { token, data });
+    // What you returned from the callback 👆
+
+    // 3️⃣ Wait for the callback to be received
+    const prediction = await wait.forToken<Prediction>(token);
+    if (!prediction.ok) {
       throw new Error("Failed to create prediction");
     }
 
-    logger.log("Result", result);
+    logger.log("Prediction", prediction);
 
-    const imageUrl = result.output.output;
+    const imageUrl = prediction.output.output;
     logger.log("Image URL", imageUrl);
   },
 });
 ```
 
 ## unwrap()
 
-We provide a handy `.unwrap()` method that will throw an error if the result is not ok. This means your happy path is a lot cleaner.
+`wait.forToken()` also supports `.unwrap()` which throws if the waitpoint times out,
+keeping the happy path clean:
 
 ```ts
-const prediction = await wait
-  .forHttpCallback<Prediction>(
-    async (url) => {
-      // ...
-    },
-    {
-      timeout: "10m",
-    }
-  )
-  .unwrap();
-// 👆 This will throw an error if the waitpoint times out
+const prediction = await wait.forToken<Prediction>(token).unwrap();
 
-// This is the actual data you sent to the callback now, not a result object
+// This is the result data that Replicate sent back (via HTTP POST)
 logger.log("Prediction", prediction);
 ```
 
 ### Options
 
-The `wait.forHttpCallback` function accepts an optional second parameter with the following properties:
+The `wait.createHttpCallback()` function accepts an optional second parameter with the following properties:
 
 <ParamField query="timeout" type="string" optional>
   The maximum amount of time to wait for the token to be completed.
@@ -104,41 +100,36 @@ The `wait.forHttpCallback` function accepts an optional second parameter with th
   Tags to attach to the token. Tags can be used to filter waitpoints in the dashboard.
 </ParamField>
 
-<ParamField query="releaseConcurrency" type="boolean" optional>
-  If set to true, this will cause the waitpoint to release the current run from the queue's concurrency.
-
-This is useful if you want to allow other runs to execute while waiting
-
-Note: It's possible that this run will not be able to resume when the waitpoint is complete if this is set to true.
-It will go back in the queue and will resume once concurrency becomes available.
-
-The default is `false`.
-
-</ParamField>
-
 ### returns
 
-The `forHttpCallback` function returns a result object with the following properties:
+`wait.createHttpCallback()` returns an object with:
 
-<ParamField query="ok" type="boolean">
+<ParamField query="token" type="object">
   Whether the token was completed successfully.
-</ParamField>
 
-<ParamField query="output" type="any">
-  If `ok` is `true`, this will be the output of the token.
+  <Expandable title="properties" defaultOpen={true}>
+    <ParamField query="id" type="string">
+      The ID of the token. Starts with `waitpoint_`.
+    </ParamField>
+    <ParamField query="isCached" type="boolean">
+      Whether the token is cached. Will return true if the token was created with an idempotency key and
+      the same idempotency key was used again.
+    </ParamField>
+
+      <ParamField query="url" type="string">
+        The URL that was created for the waitpoint. Call this via an HTTP POST request to complete the
+        waitpoint and continue the run with the JSON body of the request.
+      </ParamField>
+
+  </Expandable>
 </ParamField>
 
-<ParamField query="error" type="Error">
-  If `ok` is `false`, this will be the error that occurred. The only error that can occur is a
-  timeout error.
+<ParamField query="data" type="object">
+  If you returned anything from the function, it will be here.
 </ParamField>
 
-### unwrap() returns
-
-If you use the `unwrap()` method, it will just return the output of the token. If an error occurs it will throw an error.
-
-## The format of the callback request
+## Calling the callback URL yourself
 
-If you want to offload work to one of your own services you will need to do the callback request yourself.
+`wait.createHttpCallback()` returns a unique one-time-use URL.
 
-The `wait.forHttpCallback()` function gives you a unique one-time use URL. You should do a `POST` request to this URL with a text body that is JSON parseable.
+You should do a `POST` request to this URL with a text body that is JSON-parseable. If there's no body it will use an empty object `{}`.