Request hook

note

This functionality is only available on paid plans. Check our plans here.

A request hook allows you to make modifications to the request parameters, before the request leaves the browser.

Here's an example, the below script redirects the request to the URL api/development/users when a request header x-api-development is present.

This is just the tip of the iceberg! 🧊

With custom scripts, you have the flexibility to modify the request just like you would do with code in your application; however with a tweak hook you have the unparalleled advantage of running this code without needing to deploy your application. You can quickly put together a script that works seamlessly across any environment.

Here is a diagram explaining the lifecycle of a request intercepted by a modify rule using a request hook. It's very important to understand how and when tweak runs your code. This understanding is essential to implement effective scripts.

In step 4, the HTTP request runs through additional data transformations depending on the code you write.

Context

You can access the following provided variables within the request hook.

Property	Description
method (object|string)	The HTTP method
url (string)	Request URL
body (string)	HTTP request body (request payload)
headers (object<string,string>)	HTTP request headers
vars (object)	Key-value structure that holds user defined tweak variables, if applicable (e.g. var.customId accesses a variable with name customId)
chance (object)	Holds a chance.js instance that allows you to generate random data (e.g. chance.word() generates a random word)
_ (object)	Holds a lodash instance with the utilities: isEqual, merge and pick. Same as response hook

Additional features

You can reference variables and use data generators in this editor. Both features work through context injected in the request hook environment that you can leverage. Similarly to lodash functions, here's how you can use variables & data generators. Suppose you define the variable with name first_name, here's how you can invoke it:

// append additional properties to request body
const bodyObject = JSON.stringify(body);
return {
  ...bodyObject,
  firstName: vars.first_name, // access your variables through the plain object "vars"
  age: chance.age(), // use any function from the chance.js API to generate random data
};

Errors and troubleshooting

When a request hook fails, tweak reports it on that rule's own editor, in a red footer docked under your code. There is no toast to catch before it disappears, and no guessing which of your rules broke.

The failure below is the one specific to this hook: the code ran fine, but what it returned was not the full contract.

A request hook must return every field of { method, url, body, headers }, even the ones you did not change. Returning a subset is not treated as "leave the rest alone", it is an error, and this footer is how tweak says which field is missing. The shortest correct hook is:

return { url, method, body, headers };

The footer carries everything tweak could work out about the failure:

• What kind of failure it was — the hook threw while running, it could not be compiled, or it returned a value tweak cannot use.
• Where in your code, as a line, col chip, with that line of your own hook printed underneath it. The position is mapped back onto what you wrote, so line 1 means line 1 of your hook. A contract failure has no position, because nothing threw.
• Which request triggered it, method and url, and the time it happened.
• Show stack trace expands the first frames of the original error, when there is one.

The rule name grows a small red mark too, so a folded rule still tells you it has something to report. Clicking that mark unfolds the rule straight onto the hook that failed.

The footer stays until you dismiss it with the ✕. It is replaced, not stacked, when the same rule fails again, so a hook breaking on every request cannot bury the popup.

Common causes

What you see	Usually means
A returned value tweak cannot use	The hook returned a subset of the contract, or something that is not an object at all. Return all four fields.
The request goes out unchanged	Nothing was returned. A hook that returns nothing leaves the request as it was, on purpose.
TypeError reading something off body	body is the raw request body. Parse it before reading fields off it, and expect it to be empty on a GET.

tip

console.log works inside a hook and prints to the page's own console, which is the quickest way to see what url, body and headers actually hold before you write against them.

Let an AI coding tool write the hook

A hook is a small, self-contained script against a documented contract, which is exactly the kind of thing AI coding tools are good at. Point yours at this page and describe what you want:

Read https://tweak-extension.com/docs/rule/request-hook and write me a tweak request hook that <what you want it to do>.

The page tells the tool everything it needs: the variables tweak injects, the { method, url, body, headers } contract every hook has to return, and the utilities available. Paste the result into the editor and run the request once to confirm it does what you meant.

Prominent use cases

Here's a list of the most common use cases for this feature:

• Redirect a request URL (e.g. from a production environment to a staging or development environment) or dynamicall appending query parameters. If a static redirect is all you need, a redirect rule it's highly recommended, it without any code, and works on requests your JavaScript never makes (scripts, stylesheets, images, the page navigation itself).
• Programmatically modify the request body based on custom logic (e.g. build a dynamic request body depending on the URL path and query parameters).
• Append additional request headers to the request (also possible with through the request headers table).

---

Was this page helpful?

Need something else? Request a feature

  Thanks for your feedback!