Transforms API

Transforms modify webhook payloads before delivery using JSONata, JavaScript, TypeScript, Liquid, XSLT, JMESPath, JSON Logic or jq.

Endpoints

Method	Path	Description
GET	`/api/transforms`	List transforms
GET	`/api/transforms/engines`	List the transform languages this deployment supports
POST	`/api/transforms`	Create transform
GET	`/api/transforms/{id}`	Get transform
PATCH	`/api/transforms/{id}`	Update transform
DELETE	`/api/transforms/{id}`	Delete transform

Transform Object

{
  "id": "88888888-8888-4888-8888-888888888888",
  "name": "GitHub to Slack",
  "description": "Format GitHub events for Slack",
  "transformType": "javascript",
  "code": "function transform(payload) { return { text: payload.action }; }",
  "inputFormat": "json",
  "outputFormat": "json",
  "routeCount": 3,
  "createdAt": "2024-01-01T00:00:00Z",
  "updatedAt": "2024-01-15T10:30:00Z"
}

Transform Types

Type	Description
`jsonata`	JSONata expression (default)
`javascript`	JavaScript `transform(data)` function, run in a QuickJS sandbox
`typescript`	TypeScript `transform(data)` function. Types are stripped, not checked, then it runs like JavaScript
`liquid`	Liquid template
`xslt`	XSLT stylesheet
`jmespath`	JMESPath expression
`jsonlogic`	JSON Logic rule. Declarative, with no code execution
`jq`	jq program. Needs transform isolation; see List Transform Engines

Input/Output Formats

Format	Description
`json`	JSON (default)
`xml`	XML
`text`	Plain text

List Transforms

GET /api/transforms

Query Parameters

Parameter	Type	Description
page	number	Page number (default: 1)
pageSize	number	Items per page (default: 20, max: 100)

Example

curl https://api.hookbase.app/api/transforms \
  -H "Authorization: Bearer whr_your_api_key"

Response

{
  "transforms": [
    {
      "id": "88888888-8888-4888-8888-888888888888",
      "name": "GitHub to Slack",
      "transformType": "javascript",
      "routeCount": 3,
      "createdAt": "2024-01-01T00:00:00Z"
    }
  ],
  "pagination": {
    "total": 5,
    "page": 1,
    "pageSize": 20
  }
}

List Transform Engines

GET /api/transforms/engines

Lists every transform language, with a starter snippet for each and whether this deployment can use it right now. Clients should show an unavailable language as disabled rather than hide it.

Response

{
  "engines": [
    {
      "type": "jsonata",
      "label": "JSONata",
      "description": "Query and transformation language for JSON.",
      "fileExtension": "jsonata",
      "starterCode": "{\n  \"id\": id,\n  \"total\": $sum(items.price)\n}",
      "aiGenerate": true,
      "available": true
    },
    {
      "type": "jq",
      "label": "jq",
      "description": "The jq JSON processor. Needs transform isolation to run.",
      "fileExtension": "jq",
      "starterCode": "{id: .id, total: ([.items[].price] | add)}",
      "aiGenerate": true,
      "available": false
    }
  ],
  "contentFormats": ["json", "xml", "text"]
}

Field	Description
type	Value for `transformType`
label	Display name
description	One-line summary
fileExtension	File extension editors and the CLI use for this language, without the dot
starterCode	A minimal working transform
aiGenerate	Whether AI generation supports this language. Every language except XSLT does
available	`false` when this deployment refuses the language. jq is `false` unless transform isolation is enabled

Creating, updating or testing a transform in an unavailable language returns 400 with the code TRANSFORM_ENGINE_UNAVAILABLE.

Create Transform

POST /api/transforms

Request Body

Field	Type	Required	Description
name	string	Yes	Display name
code	string	Yes	Transform code
description	string	No	Optional description
transformType	string	No	Transform type (default: `jsonata`). See Transform Types
inputFormat	string	No	Input format (default: `json`)
outputFormat	string	No	Output format (default: `json`)

Example

curl -X POST https://api.hookbase.app/api/transforms \
  -H "Authorization: Bearer whr_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Extract Fields",
    "transformType": "jsonata",
    "code": "{ \"event\": action, \"repo\": repository.full_name }",
    "description": "Extract key fields from GitHub webhooks"
  }'

Response

{
  "transform": {
    "id": "88888888-8888-4888-8888-888888880001",
    "name": "Extract Fields",
    "description": "Extract key fields from GitHub webhooks",
    "transformType": "jsonata",
    "code": "{ \"event\": action, \"repo\": repository.full_name }",
    "inputFormat": "json",
    "outputFormat": "json",
    "routeCount": 0,
    "createdAt": "2024-01-15T10:30:00Z",
    "updatedAt": "2024-01-15T10:30:00Z"
  }
}

Tip

The code is validated on creation. If there are syntax errors, the API returns a 400 response with details about the error.

Get Transform

GET /api/transforms/{id}

Example

curl https://api.hookbase.app/api/transforms/88888888-8888-4888-8888-888888888888 \
  -H "Authorization: Bearer whr_your_api_key"

Response

Returns the full transform object.

Update Transform

PATCH /api/transforms/{id}

Request Body

All fields are optional. Only provided fields are updated.

Field	Type	Description
name	string	Display name
code	string	Transform code
description	string	Optional description
transformType	string	Transform type
inputFormat	string	Input format
outputFormat	string	Output format

Example

curl -X PATCH https://api.hookbase.app/api/transforms/88888888-8888-4888-8888-888888888888 \
  -H "Authorization: Bearer whr_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "{ \"event\": action, \"repo\": repository.full_name, \"sender\": sender.login }"
  }'

Response

Returns the updated transform object.

Delete Transform

DELETE /api/transforms/{id}

Warning

A transform cannot be deleted while it is assigned to active routes. Remove it from all routes first.

Example

curl -X DELETE https://api.hookbase.app/api/transforms/88888888-8888-4888-8888-888888888888 \
  -H "Authorization: Bearer whr_your_api_key"

Response

204 No Content

Error Responses

400 Bad Request

Invalid transform code:

{
  "error": "Bad Request",
  "message": "Transform code validation failed: Unexpected token at position 15",
  "code": "INVALID_CODE"
}

Language not available on this deployment (for example jq without transform isolation):

{
  "error": "jq transforms are not available on this deployment yet (they need transform isolation)",
  "code": "TRANSFORM_ENGINE_UNAVAILABLE"
}

404 Not Found

Transform not found:

{
  "error": "Not Found",
  "message": "Transform with ID 88888888-8888-4888-8888-888888880002 not found",
  "code": "RESOURCE_NOT_FOUND"
}

409 Conflict

Transform in use:

{
  "error": "Conflict",
  "message": "Transform is assigned to 3 active routes",
  "code": "RESOURCE_IN_USE"
}

Transforms Guide — Types, examples, and best practices
Routes API — Assign transforms to routes

Transforms API

Transforms modify webhook payloads before delivery using JSONata, JavaScript, TypeScript, Liquid, XSLT, JMESPath, JSON Logic or jq.

Endpoints

Method	Path	Description
GET	`/api/transforms`	List transforms
GET	`/api/transforms/engines`	List the transform languages this deployment supports
POST	`/api/transforms`	Create transform
GET	`/api/transforms/{id}`	Get transform
PATCH	`/api/transforms/{id}`	Update transform
DELETE	`/api/transforms/{id}`	Delete transform

Transform Object

{
  "id": "88888888-8888-4888-8888-888888888888",
  "name": "GitHub to Slack",
  "description": "Format GitHub events for Slack",
  "transformType": "javascript",
  "code": "function transform(payload) { return { text: payload.action }; }",
  "inputFormat": "json",
  "outputFormat": "json",
  "routeCount": 3,
  "createdAt": "2024-01-01T00:00:00Z",
  "updatedAt": "2024-01-15T10:30:00Z"
}

Transform Types

Type	Description
`jsonata`	JSONata expression (default)
`javascript`	JavaScript `transform(data)` function, run in a QuickJS sandbox
`typescript`	TypeScript `transform(data)` function. Types are stripped, not checked, then it runs like JavaScript
`liquid`	Liquid template
`xslt`	XSLT stylesheet
`jmespath`	JMESPath expression
`jsonlogic`	JSON Logic rule. Declarative, with no code execution
`jq`	jq program. Needs transform isolation; see List Transform Engines

Input/Output Formats

Format	Description
`json`	JSON (default)
`xml`	XML
`text`	Plain text

List Transforms

GET /api/transforms

Query Parameters

Parameter	Type	Description
page	number	Page number (default: 1)
pageSize	number	Items per page (default: 20, max: 100)

Example

curl https://api.hookbase.app/api/transforms \
  -H "Authorization: Bearer whr_your_api_key"

Response

{
  "transforms": [
    {
      "id": "88888888-8888-4888-8888-888888888888",
      "name": "GitHub to Slack",
      "transformType": "javascript",
      "routeCount": 3,
      "createdAt": "2024-01-01T00:00:00Z"
    }
  ],
  "pagination": {
    "total": 5,
    "page": 1,
    "pageSize": 20
  }
}

List Transform Engines

GET /api/transforms/engines

Lists every transform language, with a starter snippet for each and whether this deployment can use it right now. Clients should show an unavailable language as disabled rather than hide it.

Response

{
  "engines": [
    {
      "type": "jsonata",
      "label": "JSONata",
      "description": "Query and transformation language for JSON.",
      "fileExtension": "jsonata",
      "starterCode": "{\n  \"id\": id,\n  \"total\": $sum(items.price)\n}",
      "aiGenerate": true,
      "available": true
    },
    {
      "type": "jq",
      "label": "jq",
      "description": "The jq JSON processor. Needs transform isolation to run.",
      "fileExtension": "jq",
      "starterCode": "{id: .id, total: ([.items[].price] | add)}",
      "aiGenerate": true,
      "available": false
    }
  ],
  "contentFormats": ["json", "xml", "text"]
}

Field	Description
type	Value for `transformType`
label	Display name
description	One-line summary
fileExtension	File extension editors and the CLI use for this language, without the dot
starterCode	A minimal working transform
aiGenerate	Whether AI generation supports this language. Every language except XSLT does
available	`false` when this deployment refuses the language. jq is `false` unless transform isolation is enabled

Creating, updating or testing a transform in an unavailable language returns 400 with the code TRANSFORM_ENGINE_UNAVAILABLE.

Create Transform

POST /api/transforms

Request Body

Field	Type	Required	Description
name	string	Yes	Display name
code	string	Yes	Transform code
description	string	No	Optional description
transformType	string	No	Transform type (default: `jsonata`). See Transform Types
inputFormat	string	No	Input format (default: `json`)
outputFormat	string	No	Output format (default: `json`)

Example

curl -X POST https://api.hookbase.app/api/transforms \
  -H "Authorization: Bearer whr_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Extract Fields",
    "transformType": "jsonata",
    "code": "{ \"event\": action, \"repo\": repository.full_name }",
    "description": "Extract key fields from GitHub webhooks"
  }'

Response

{
  "transform": {
    "id": "88888888-8888-4888-8888-888888880001",
    "name": "Extract Fields",
    "description": "Extract key fields from GitHub webhooks",
    "transformType": "jsonata",
    "code": "{ \"event\": action, \"repo\": repository.full_name }",
    "inputFormat": "json",
    "outputFormat": "json",
    "routeCount": 0,
    "createdAt": "2024-01-15T10:30:00Z",
    "updatedAt": "2024-01-15T10:30:00Z"
  }
}

Tip

The code is validated on creation. If there are syntax errors, the API returns a 400 response with details about the error.

Get Transform

GET /api/transforms/{id}

Example

curl https://api.hookbase.app/api/transforms/88888888-8888-4888-8888-888888888888 \
  -H "Authorization: Bearer whr_your_api_key"

Response

Returns the full transform object.

Update Transform

PATCH /api/transforms/{id}

Request Body

All fields are optional. Only provided fields are updated.

Field	Type	Description
name	string	Display name
code	string	Transform code
description	string	Optional description
transformType	string	Transform type
inputFormat	string	Input format
outputFormat	string	Output format

Example

curl -X PATCH https://api.hookbase.app/api/transforms/88888888-8888-4888-8888-888888888888 \
  -H "Authorization: Bearer whr_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "{ \"event\": action, \"repo\": repository.full_name, \"sender\": sender.login }"
  }'

Response

Returns the updated transform object.

Delete Transform

DELETE /api/transforms/{id}

Warning

A transform cannot be deleted while it is assigned to active routes. Remove it from all routes first.

Example

curl -X DELETE https://api.hookbase.app/api/transforms/88888888-8888-4888-8888-888888888888 \
  -H "Authorization: Bearer whr_your_api_key"

Response

204 No Content

Error Responses

400 Bad Request

Invalid transform code:

{
  "error": "Bad Request",
  "message": "Transform code validation failed: Unexpected token at position 15",
  "code": "INVALID_CODE"
}

Language not available on this deployment (for example jq without transform isolation):

{
  "error": "jq transforms are not available on this deployment yet (they need transform isolation)",
  "code": "TRANSFORM_ENGINE_UNAVAILABLE"
}

404 Not Found

Transform not found:

{
  "error": "Not Found",
  "message": "Transform with ID 88888888-8888-4888-8888-888888880002 not found",
  "code": "RESOURCE_NOT_FOUND"
}

409 Conflict

Transform in use:

{
  "error": "Conflict",
  "message": "Transform is assigned to 3 active routes",
  "code": "RESOURCE_IN_USE"
}

Transforms Guide — Types, examples, and best practices
Routes API — Assign transforms to routes