# Pabbly Hook

> **Per-section URLs available** — append `.md` to any docs URL for markdown:
> - Endpoint: `/pabbly/hook/{tagSlug}/{endpointSlug}.md`
> - Resource object: `/pabbly/hook/{tagSlug}/object.md`
> - Guide page: `/pabbly/hook/guides/{docSlug}.md`
>
> Or send `Accept: text/markdown` on the canonical URL.

> REST API for Pabbly Hook

- Base URL: `https://hook.pabbly.com/api/v1`
- Authentication: Basic token via `Authorization` header
- Version: v1

---

## Guides

### Overview

The Pabbly Hook API lets you programmatically manage webhook connections, transformations, events, and folders. Build, modify, and route incoming webhook payloads to downstream services through code, and automate the connections you would otherwise wire up in the Pabbly Hook dashboard.

*Example request*

```bash
curl https://hook.pabbly.com/api/v1/folders \
  -u {{YOUR_API_KEY}}:{{YOUR_SECRET_KEY}}
```

**Base URL**

All endpoints are relative to the base URL below. Combine the base URL with the path on each endpoint to get the full request URL.

*Base URL*

```text
https://hook.pabbly.com/api/v1
```

**Requests and responses**

The API accepts JSON request bodies and returns JSON responses. Send `Content-Type: application/json` on every request that has a body. Path parameters are interpolated into the URL; query parameters and body fields are documented per endpoint.

*Success response*

```json
{
  "success": true,
  "data": { /* … */ }
}
```

**Errors**

When a request fails, the response status code reflects the error category and the body carries a human-readable message. Treat any non-2xx status as a failure.

| Status | Meaning |
|---|---|
| 200, 201 | Success |
| 400 | Bad request — missing or malformed parameters |
| 401 | Unauthorized — missing or invalid API credentials |
| 404 | Not found — the resource does not exist |
| 429 | Too many requests |
| 5xx | Server error — retry with backoff |

*Error response*

```json
{
  "success": false,
  "error": "A human-readable explanation"
}
```

### Authentication

The Pabbly Hook API uses **HTTP Basic Auth**. Every request must include your API Key and Secret Key as the username and password.

*Auth header*

```http
Authorization: Basic <base64({{YOUR_API_KEY}}:{{YOUR_SECRET_KEY}})>
```

**Getting your credentials**

Sign in to your Pabbly account and navigate to **Settings → API Settings → Generate the Keys**. You will see (or be able to generate) an **API Key** and a matching **Secret Key**. Treat the Secret Key like a password.

**Making authenticated requests**

Send your API Key as the HTTP Basic username and your Secret Key as the password on every request. The examples on the right show how to call /folders with proper authentication.

*cURL*

```bash
curl https://hook.pabbly.com/api/v1/folders \
  -u {{YOUR_API_KEY}}:{{YOUR_SECRET_KEY}}
```

*Node.js*

```javascript
const credentials = Buffer
  .from('{{YOUR_API_KEY}}:{{YOUR_SECRET_KEY}}')
  .toString('base64');

const response = await fetch(
  'https://hook.pabbly.com/api/v1/folders',
  { headers: { Authorization: `Basic ${credentials}` } }
);
const data = await response.json();
```

*Python*

```python
import requests
from requests.auth import HTTPBasicAuth

response = requests.get(
    'https://hook.pabbly.com/api/v1/folders',
    auth=HTTPBasicAuth('{{YOUR_API_KEY}}', '{{YOUR_SECRET_KEY}}'),
)
data = response.json()
```

**Keep your credentials secret**

Your credentials grant full access to your account. Never embed them in browser-side code, commit them to version control, or share them in support tickets. If you suspect a credential has been exposed, rotate it from the dashboard (**Settings → API Settings → Generate the Keys**) and update any servers that use it.

---

## API Reference

### Folder

#### POST /folders — Create Folder

Create a new folder to group related webhook connections in your Pabbly Hook workspace.

**Body parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| name | string | No |  |

#### GET /folders — Get All Folders

Return every folder in the account along with its ID and name.

#### PUT /folders/rename/{{folderId}} — Rename Folder Name

Change the display name of an existing folder identified by its ID.

**Path parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| folderId | string | Yes |  |

**Body parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| name | string | No |  |

#### PUT /folders/move-connection — Move Connection From Folder

Move a connection out of its current folder and into a different one.

**Body parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| connectionIds | array | No |  |
| fromFolderId | string | No |  |
| toFolderId | string | No |  |

#### DELETE /folders/{{folderId}} — Delete Folder And Move Connections to Home Folder

Delete a folder and relocate every connection inside it to the root (home) folder.

**Path parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| folderId | string | Yes |  |

### Connection

#### POST /connections — Create Connection

Create a new webhook connection that accepts incoming HTTP requests and forwards them through your configured workflow.

**Body parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| name | string | No |  |
| folder_id | string | No |  |
| source | object | No |  |
|   ↳ allowed_http_methods | array | No |  |
|   ↳ custom_response | object | No |  |
|     ↳ status | string | No |  |
|     ↳ content_type | string | No |  |
|     ↳ content | object | No |  |
|       ↳ name | string | No |  |
|       ↳ details | object | No |  |
|         ↳ age | string | No |  |
| destination | object | No |  |
|   ↳ url | string | No |  |
|   ↳ rate_limit | integer | No |  |
|   ↳ rate_limit_period | string | No |  |
|   ↳ http_method | string | No |  |
| retry | object | No |  |
|   ↳ status | string | No |  |
|   ↳ limit | integer | No |  |
|   ↳ interval | integer | No |  |
|   ↳ time_limit_period | string | No |  |
|   ↳ strategy | string | No |  |
| delay | object | No |  |
|   ↳ status | string | No |  |
|   ↳ interval | integer | No |  |
| trs_id | string | No |  |
| filter | object | No |  |
|   ↳ status | string | No |  |
|   ↳ body | object | No |  |
|     ↳ amount | object | No |  |
|       ↳ $gt | integer | No |  |
|     ↳ category | object | No |  |
|       ↳ $eq | string | No |  |
|   ↳ headers | object | No |  |
|     ↳ content_type | string | No |  |
|   ↳ query | object | No |  |
|     ↳ param1 | string | No |  |
|     ↳ param2 | string | No |  |
|   ↳ path | string | No |  |

#### PATCH /connections/{{connectionId}} — Update Connection

Partially update a connection's attributes — name, settings, transformations — without replacing the full resource.

**Path parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| connectionId | string | Yes |  |

**Body parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| name | string | No |  |
| source | object | No |  |
|   ↳ allowed_http_methods | array | No |  |
|   ↳ custom_response | object | No |  |
|     ↳ status | string | No |  |
|     ↳ content_type | string | No |  |
|     ↳ content | object | No |  |
|       ↳ name | string | No |  |
|       ↳ details | object | No |  |
|         ↳ age | string | No |  |
| destination | object | No |  |
|   ↳ url | string | No |  |
|   ↳ rate_limit | integer | No |  |
|   ↳ rate_limit_period | string | No |  |
|   ↳ http_method | string | No |  |
| retry | object | No |  |
|   ↳ status | string | No |  |
|   ↳ limit | integer | No |  |
|   ↳ interval | integer | No |  |
|   ↳ time_limit_period | string | No |  |
|   ↳ strategy | string | No |  |
| delay | object | No |  |
|   ↳ status | string | No |  |
|   ↳ interval | integer | No |  |
|   ↳ time_limit_period | string | No |  |
| trs_id | string | No |  |
| filter | object | No |  |
|   ↳ status | string | No |  |
|   ↳ body | object | No |  |
|     ↳ amount | object | No |  |
|       ↳ $gt | integer | No |  |
|     ↳ category | object | No |  |
|       ↳ $eq | string | No |  |
|   ↳ headers | object | No |  |
|     ↳ content_type | string | No |  |
|   ↳ query | object | No |  |
|     ↳ param1 | string | No |  |
|     ↳ param2 | string | No |  |
|   ↳ path | string | No |  |

#### PUT /connections/disable — Disable Connection

Stop a connection from accepting incoming webhook requests. Existing history is retained; new triggers are rejected until re-enabled.

**Body parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| connection_ids | array | No |  |

#### PUT /connections/enable — Enable Connection

Re-activate a previously disabled connection so it can receive webhook requests again.

**Body parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| connection_ids | array | No |  |

#### DELETE /connections/ — Delete Connection And Move To Trash

Soft-delete a connection by moving it to trash. Can be restored within the retention window before permanent deletion.

**Body parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| connection_ids | array | No |  |

#### GET /connections — Filter Connection

List connections matching the specified filters (folder, status, name).

**Query parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| filter | boolean | No |  |
| status | string | No |  |
| folder_id | string | No |  |
| name | string | No |  |
| page | integer | No |  |
| limit | integer | No |  |

#### GET /connections/{{connectionId}} — Get Single Connection By Connection_id

Fetch the full details of one connection by its unique ID.

**Path parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| connectionId | string | Yes |  |

### Transformation

#### POST /transformations — Create Transformation

Create a transformation rule that modifies incoming webhook payloads before they're forwarded to downstream services.

**Body parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| name | string | No |  |
| code | string | No |  |

#### GET /transformations/{{transformationId}} — Get Single Transformation By Trs_id

Fetch the full configuration of one transformation by its unique transformation ID.

**Path parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| transformationId | string | Yes |  |

#### GET /transformations/get-all/ — Get All Transformation

List every transformation defined in the account.

#### PUT /transformations/{{transformationId}} — Update Transformation By Trs_id

Update an existing transformation's rules or output mapping.

**Path parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| transformationId | string | Yes |  |

**Body parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| name | string | No |  |
| code | string | No |  |

#### DELETE /transformations/{{transformationId}} — Delete Transformation Based On Trs_id

Permanently delete a transformation. Connections using it fall back to passing payloads through unchanged.

**Path parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| transformationId | string | Yes |  |

### Request

#### GET /requests — Filter Request

List incoming webhook requests matching the specified filters (connection, date range, status).

**Query parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| filter | boolean | No |  |
| connection_id | string | No |  |
| requestId | string | No |  |
| status | string | No |  |
| dateRange | string | No |  |
| page | integer | No |  |
| limit | integer | No |  |

#### GET /requests — Retrieve All Request

Return the full history of incoming webhook requests for the account.

**Query parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| page | integer | No |  |
| limit | integer | No |  |

### Event

#### GET /events — Filter Events

List webhook delivery events matching the specified filters (connection, status, date range).

**Query parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| filter | boolean | No |  |
| limit | integer | No |  |
| requestId | string | No |  |
| status | string | No |  |

#### GET /events — Retrieve All Events

Return the full event log of webhook deliveries for the account.

**Query parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| page | integer | No |  |
| limit | integer | No |  |