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

# When webhook received

> Trigger a workflow by receiving an HTTP request from any external system

<Tip>Please note: all trigger setup can be done in AI chat. Tell AI what you want the workflow to do, and it will handle the rest.</Tip>

This trigger generates a unique URL. When an external system sends an HTTP POST to it, the workflow runs.

## Build with AI

Open the AI Chat in your table's right sidebar and describe what you want.

AI handles everything: it chooses the right trigger, maps the relevant fields, and sets up all actions automatically.

Describe the goal once, and the workflow is ready — no manual setup needed.

**Example:** *"When I receive a Stripe payment webhook, create an order record."*

## Configuration

| Setting       | Required | Description                                                                                                                      |
| ------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------- |
| Authorization | No       | **None** (public — anyone with the URL can trigger it) or **Bearer Token** (auto-generated token required in the request header) |
| Response      | No       | **Default** (Teable returns its own acknowledgement) or **Custom** (you decide the status code, content type, and body)          |

## How to set it up

1. Open your automation and add a new trigger.
2. Select **When webhook received**.
3. The trigger immediately generates a unique **webhook URL**. Copy this URL — you will need it for the external system.
4. (Optional but recommended) Click **Generate Token** to enable Bearer Token authorization. This produces a token that must be included in the `Authorization` header of incoming requests.
5. Save and activate the automation.
6. Configure your external system to send a POST request to the webhook URL. Include the token in the header if you enabled authorization.
7. Send a test request (see examples below). Check the automation's run history to verify it received the data correctly.
8. Add your action steps. Click **+** in any action field to reference values from the webhook's JSON body.

## What data is available to next steps

The entire JSON body of the incoming POST request is available as variables. For example, if you send:

```json theme={null}
{
  "order_id": "12345",
  "customer": "Alice",
  "amount": 99.95
}
```

Then in your actions, you can reference `order_id`, `customer`, and `amount` individually by clicking **+** and navigating to the trigger's output fields.

Teable automatically parses the JSON and creates named variables for each top-level key. Nested objects are also accessible.

## Customize the response

By default, Teable replies to every incoming request with its own acknowledgement. Some platforms will not accept that: they verify a subscription URL by sending a probe and requiring your endpoint to echo one field of it back. Slack works this way, so its events can only reach an automation once the webhook answers the handshake.

In the trigger panel, switch **Response** from **Default** to **Custom**:

| Field             | Description                                                                           |
| ----------------- | ------------------------------------------------------------------------------------- |
| **Status code**   | Any code from 200 to 299. Defaults to 200.                                            |
| **Content type**  | **JSON** or **raw text**. Defaults to JSON.                                           |
| **Response body** | The text to return. Use `{{body.<path>}}` to insert values from the incoming request. |

Switching to **Custom** pre-fills the body with the handshake reply most callers need:

```json theme={null}
{"challenge":"{{body.challenge}}"}
```

The paths inside `{{ }}` are the same ones the trigger exposes as output variables, so you can copy a path straight from a payload you have already seen in a test run. Nested values work too, for example `{{body.event.type}}`. In a JSON body, a path the request does not contain is rendered as `null`, so the response stays valid JSON.

<Info>Slack cannot send an `Authorization` header, so keep **Authorization** set to **None** when you connect it. The trigger panel shows a warning if both are on at once.</Info>

Switch **Response** back to **Default** at any time to return to Teable's own acknowledgement. Automations that never touch this setting are unaffected.

## Testing your webhook

The easiest way to test is with `curl` from the command line. Copy the real URL from the trigger panel rather than typing it out; it carries the base and workflow ids.

**Without authorization:**

```bash theme={null}
curl -X POST https://your-teable-instance.com/api/webhook/base/bseXXXXXXXXXXXX/workflow/wflXXXXXXXXXXXX \
  -H "Content-Type: application/json" \
  -d '{"test": true, "message": "Hello from curl"}'
```

**With Bearer Token authorization:**

```bash theme={null}
curl -X POST https://your-teable-instance.com/api/webhook/base/bseXXXXXXXXXXXX/workflow/wflXXXXXXXXXXXX \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-generated-token" \
  -d '{"order_id": "12345", "status": "paid"}'
```

**Sending more complex data:**

```bash theme={null}
curl -X POST https://your-teable-instance.com/api/webhook/base/bseXXXXXXXXXXXX/workflow/wflXXXXXXXXXXXX \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-generated-token" \
  -d '{
    "event": "invoice.paid",
    "data": {
      "invoice_id": "INV-001",
      "amount": 250.00,
      "currency": "USD",
      "customer_email": "alice@example.com"
    }
  }'
```

After sending a test request, check the automation's run history to confirm the data was received and parsed correctly.

## Rate limits

| Scope        | Limit                |
| ------------ | -------------------- |
| Per base     | 50 requests / second |
| Per workflow | 2 requests / second  |

Requests exceeding the rate limit will receive an HTTP 429 response. If your external system sends bursts of requests, consider implementing retry logic with exponential backoff.

## Security best practices

* **Always use Bearer Token authorization** for production webhooks. A public webhook URL can be triggered by anyone who discovers the URL.
* **Keep your webhook URL private.** Treat it like a password. Do not commit it to public repositories or share it in open channels.
* **Regenerate the token** if you suspect it has been compromised. You can generate a new token from the trigger panel at any time.
* **Validate data in your workflow.** Do not assume the incoming data is well-formed. Use filters or script steps to verify required fields are present before processing.
* **Monitor run history.** Regularly check your automation's run logs to spot unexpected or unauthorized requests.

## When to use

* **Receive payment events from Stripe or PayPal.** Configure a Stripe webhook to send `invoice.paid` events to your Teable automation, creating or updating order records automatically.
* **Accept form submissions from your website.** Point your website's contact or signup form to the webhook URL to create records directly in Teable.
* **Ingest data from IoT devices.** Sensors or devices that can send HTTP requests can push data into Teable for monitoring and alerting.
* **Connect CI/CD pipelines.** Trigger workflows when a build succeeds or fails — create records, send notifications, or update project status.
* **Receive events from any SaaS tool.** Many tools (GitHub, Jira, Shopify, Twilio, etc.) support webhook notifications. Point them at your Teable webhook to automate cross-tool workflows.

## Tips

* The webhook only accepts **POST** requests. GET, PUT, and other methods will not trigger the automation.
* Always send a `Content-Type: application/json` header. If the body is not valid JSON, the trigger may not parse the data correctly.
* If you need to send data from a system that does not support custom headers (for Bearer auth), consider using the public mode but adding a secret key in the JSON body that your workflow validates with a filter or script.
* For debugging, you can use services like [webhook.site](https://webhook.site) to inspect what your external system is actually sending before pointing it at Teable.

## Related

* [HTTP request action](/en/basic/automation/actions/logic/http-request) — the outbound counterpart: call external APIs from your workflow
* [Run script](/en/basic/automation/ai/scripting/runscript) — for advanced webhook payload processing
* [Loop (batch) action](/en/basic/automation/actions/logic/loop-run) — process arrays in webhook payloads