> ## Documentation Index
> Fetch the complete documentation index at: https://docs.codenullapp.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks

> Expose an HTTP endpoint in your application so external services can send data into it.

A Webhook is a hook that exposes a public HTTP endpoint in your application. Use it when an external service (Stripe, a form provider, another system, a script, etc.) needs to send data into your application by making an HTTP request.

<Info>
  Webhooks only work in one direction: an external system calls **into** your application. If instead you want your application to call an external URL when something happens (a record is created, updated, etc.), do that from a regular hook (for example `afterSave`) using `axios` or `fetch` — see [Hooks](/configurations/hooks).
</Info>

## How to create a Webhook

1. Open **Hooks Explorer**.
2. Create a new hook (or open an existing one and go to its detail view).
3. In the **Type** dropdown, select **webHook**.
4. Fill in the fields described below and save.

## Fields

* **Name**: The identifier for this webhook. It must be at least 2 characters long and can only contain letters, numbers, `_` and `-`. This name becomes part of the URL external services will call, so keep it short and hard to guess.
* **Type**: Select **webHook**.
* **Table**: Not used by webhooks — a webhook runs at the application level, not tied to any table's records. You can leave the default value here.
* **Code**: The JavaScript code that runs every time someone calls your webhook.

## The Webhook URL

Once saved, the URL to give to the external service is:

```
https://<your-application-domain>/api/webhook/<Name>
```

For example, a webhook named `orderStatusUpdate` is called with:

```
POST https://<your-application-domain>/api/webhook/orderStatusUpdate
```

<Warning>
  If the `Name` doesn't match an existing webhook, the request gets a `404` response. Anyone who knows (or guesses) the URL can call it — there is no built-in authentication, so if you need to restrict who can call it, validate a token/header yourself inside the **Code**.
</Warning>

## Writing the code

Whatever the external system sends in the request body is available inside your code as `instance`. Whatever your code returns is sent back as the response.

```javascript theme={null}
const handleOrderUpdate = async (instance) => {
  // instance is the JSON body sent by the caller
  // e.g. { "orderId": 123, "status": "shipped" }

  if (!instance?.orderId) {
    throw new Error("orderId is required");
  }

  // ... your logic: save it, notify someone, etc.

  return { received: true, orderId: instance.orderId };
};

handleOrderUpdate(instance);
```

You can use the same helpers available in any other hook (querying the database, sending emails, importing modules, etc.) — see [Hooks](/configurations/hooks) for those examples.

If your code throws an error, the caller receives a `500` response.

## Trying it out

You can test a webhook with any HTTP client. For example, with `curl`:

```bash theme={null}
curl -X POST https://<your-application-domain>/api/webhook/orderStatusUpdate \
  -H "Content-Type: application/json" \
  -d '{"orderId": 123, "status": "shipped"}'
```

## Limits

<Warning>
  All the webhooks in an application share a limit of **10 requests per minute**. If the external service you're integrating with sends bursts of traffic, keep this in mind.
</Warning>

## Related

* [Hooks](/configurations/hooks) — General reference for hook code (querying data, sending emails, error handling).
* [Hooks Explorer](/configurations/hooks/hooks-explorer) — Where you create and edit hooks, including webhooks.