Manage transformations — sandboxed JavaScript executed against events to mutate headers, body, path, or query string before delivery. Also includes a sandboxed run endpoint for testing transformation code against sample event payloads.
openapi: 3.0.1
info:
title: Hookdeck Transformations API
version: 1.0.0
description: Manage JavaScript transformations executed against events to mutate headers, body, path, or query string before
delivery, and run them in a test sandbox.
contact:
name: Hookdeck Support
url: https://hookdeck.com/contact-us
email: info@hookdeck.com
servers:
- url: https://api.hookdeck.com/2025-07-01
description: Production API
security:
- bearerAuth: []
- basicAuth: []
tags:
- name: Transformations
description: A transformation represents JavaScript code that will be executed on a connection's requests. Transformations
are applied to connections using Rules.
paths:
/transformations:
get:
operationId: getTransformations
summary: Retrieve transformations
description: This endpoint lists transformations, or a subset of transformations.
tags:
- Transformations
responses:
'200':
description: List of transformations
content:
application/json:
schema:
$ref: '#/components/schemas/TransformationPaginatedResult'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/APIErrorResponse'
'422':
description: Unprocessable Entity
content:
application/json:
schema:
$ref: '#/components/schemas/APIErrorResponse'
parameters:
- in: query
name: id
schema:
anyOf:
- type: string
maxLength: 255
- type: array
items:
type: string
maxLength: 255
description: Filter by transformation IDs
- in: query
name: name
schema:
anyOf:
- type: string
pattern: ^[A-z0-9-_]+$
maxLength: 155
nullable: true
- $ref: '#/components/schemas/Operators'
description: Filter by transformation name
- in: query
name: order_by
schema:
type: string
maxLength: 255
enum:
- name
- created_at
- updated_at
description: Sort key
- in: query
name: dir
schema:
type: string
enum:
- asc
- desc
description: Sort direction
- in: query
name: limit
schema:
type: integer
minimum: 0
maximum: 255
description: Result set size
- in: query
name: next
schema:
type: string
maxLength: 255
description: The ID to provide in the query to get the next set of results
- in: query
name: prev
schema:
type: string
maxLength: 255
description: The ID to provide in the query to get the previous set of results
post:
operationId: createTransformation
summary: Create a transformation
description: This endpoint creates a transformation.
tags:
- Transformations
responses:
'200':
description: A single transformation
content:
application/json:
schema:
$ref: '#/components/schemas/Transformation'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/APIErrorResponse'
'422':
description: Unprocessable Entity
content:
application/json:
schema:
$ref: '#/components/schemas/APIErrorResponse'
parameters: []
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
name:
type: string
pattern: ^[A-z0-9-_]+$
maxLength: 155
description: A unique, human-friendly name for the transformation
code:
type: string
description: JavaScript code to be executed as string
env:
type: object
properties: {}
additionalProperties:
type: string
description: Key-value environment variables to be passed to the transformation
required:
- name
- code
additionalProperties: false
put:
operationId: upsertTransformation
summary: Create/Update a transformation
description: This endpoint creates a transformation, or updates an existing transformation by name.
tags:
- Transformations
responses:
'200':
description: A single transformation
content:
application/json:
schema:
$ref: '#/components/schemas/Transformation'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/APIErrorResponse'
'422':
description: Unprocessable Entity
content:
application/json:
schema:
$ref: '#/components/schemas/APIErrorResponse'
parameters: []
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
name:
type: string
pattern: ^[A-z0-9-_]+$
maxLength: 155
description: A unique, human-friendly name for the transformation
code:
type: string
description: JavaScript code to be executed as string
env:
type: object
properties: {}
additionalProperties:
type: string
description: Key-value environment variables to be passed to the transformation
required:
- name
- code
additionalProperties: false
/transformations/count:
get:
operationId: getTransformationsCount
summary: Get transformations count
description: ''
tags:
- Transformations
responses:
'200':
description: Count of transformations
content:
application/json:
schema:
type: object
properties:
count:
type: number
format: float
description: Number of transformations
required:
- count
additionalProperties: false
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/APIErrorResponse'
'422':
description: Unprocessable Entity
content:
application/json:
schema:
$ref: '#/components/schemas/APIErrorResponse'
parameters: []
/transformations/{id}:
get:
operationId: getTransformation
summary: Retrieve a transformation
description: This endpoint retrieves a specific transformation.
tags:
- Transformations
responses:
'200':
description: A single transformation
content:
application/json:
schema:
$ref: '#/components/schemas/Transformation'
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/APIErrorResponse'
parameters:
- in: path
name: id
schema:
type: string
description: Transformation ID
required: true
delete:
operationId: deleteTransformation
summary: Delete a transformation
description: This endpoint permanently deletes a transformation. This action cannot be undone.
tags:
- Transformations
responses:
'200':
description: An object with deleted transformation id
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: ID of the Transformation
required:
- id
additionalProperties: false
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/APIErrorResponse'
parameters:
- in: path
name: id
schema:
type: string
description: Transformation ID
required: true
put:
operationId: updateTransformation
summary: Update a transformation
description: This endpoint updates a transformation.
tags:
- Transformations
responses:
'200':
description: A single transformation
content:
application/json:
schema:
$ref: '#/components/schemas/Transformation'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/APIErrorResponse'
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/APIErrorResponse'
'422':
description: Unprocessable Entity
content:
application/json:
schema:
$ref: '#/components/schemas/APIErrorResponse'
parameters:
- in: path
name: id
schema:
type: string
description: Transformation ID
required: true
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
name:
type: string
pattern: ^[A-z0-9-_]+$
maxLength: 155
description: A unique, human-friendly name for the transformation
code:
type: string
description: JavaScript code to be executed
env:
type: object
properties: {}
additionalProperties:
type: string
description: Key-value environment variables to be passed to the transformation
additionalProperties: false
/transformations/run:
put:
operationId: testTransformation
summary: Test a transformation
description: This endpoint executes a transformation against a sample request payload and returns the transformed result
without persisting anything.
tags:
- Transformations
responses:
'200':
description: Transformation run output
content:
application/json:
schema:
$ref: '#/components/schemas/TransformationExecutorOutput'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/APIErrorResponse'
'422':
description: Unprocessable Entity
content:
application/json:
schema:
$ref: '#/components/schemas/APIErrorResponse'
parameters: []
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
env:
type: object
properties: {}
additionalProperties:
type: string
description: Key-value environment variables to be passed to the transformation
webhook_id:
type: string
description: ID of the connection (webhook) to use for the execution `context`
code:
type: string
description: JavaScript code to be executed
transformation_id:
type: string
description: Transformation ID
request:
type: object
properties:
headers:
type: object
properties: {}
additionalProperties:
type: string
description: Headers of the request
x-docs-force-simple-type: true
x-docs-type: JSON
body:
anyOf:
- type: object
properties: {}
additionalProperties: false
x-docs-force-simple-type: true
x-docs-type: JSON
- type: string
description: Body of the request
x-docs-force-simple-type: true
path:
type: string
nullable: true
description: Path of the request
query:
type: string
nullable: true
description: String representation of the query params of the request
parsed_query:
type: object
properties: {}
additionalProperties: false
description: JSON representation of the query params
x-docs-force-simple-type: true
x-docs-type: JSON
required:
- headers
additionalProperties: false
description: Request input to use for the transformation execution
event_id:
type: string
x-docs-hide: true
additionalProperties: false
/transformations/{id}/executions:
get:
operationId: getTransformationExecutions
summary: Get transformation executions
description: ''
tags:
- Transformations
responses:
'200':
description: List of transformation executions
content:
application/json:
schema:
$ref: '#/components/schemas/TransformationExecutionPaginatedResult'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/APIErrorResponse'
'422':
description: Unprocessable Entity
content:
application/json:
schema:
$ref: '#/components/schemas/APIErrorResponse'
parameters:
- in: query
name: log_level
schema:
anyOf:
- type: string
enum:
- debug
- info
- warn
- error
- fatal
nullable: true
- type: array
items:
type: string
enum:
- debug
- info
- warn
- error
- fatal
nullable: true
description: Log level of the execution
- in: query
name: webhook_id
schema:
anyOf:
- type: string
maxLength: 255
- type: array
items:
type: string
maxLength: 255
description: ID of the connection the execution was run for
- in: query
name: issue_id
schema:
anyOf:
- type: string
maxLength: 255
- type: array
items:
type: string
maxLength: 255
description: ID of the associated issue
- in: query
name: created_at
schema:
anyOf:
- type: string
format: date-time
- $ref: '#/components/schemas/Operators'
description: ISO date of the transformation's execution
- in: query
name: order_by
schema:
anyOf:
- type: string
maxLength: 255
enum:
- created_at
- type: array
items:
type: string
maxLength: 255
enum:
- created_at
minItems: 2
maxItems: 2
description: Sort key(s)
- in: query
name: dir
schema:
anyOf:
- type: string
enum:
- asc
- desc
- type: array
items:
type: string
enum:
- asc
- desc
minItems: 2
maxItems: 2
description: Sort direction(s)
- in: query
name: limit
schema:
type: integer
minimum: 0
maximum: 255
description: Result set size
- in: query
name: next
schema:
type: string
maxLength: 255
description: The ID to provide in the query to get the next set of results
- in: query
name: prev
schema:
type: string
maxLength: 255
description: The ID to provide in the query to get the previous set of results
- in: path
name: id
schema:
type: string
description: Transformation ID
required: true
/transformations/{id}/executions/{execution_id}:
get:
operationId: getTransformationExecution
summary: Get a transformation execution
description: ''
tags:
- Transformations
responses:
'200':
description: A single transformation execution
content:
application/json:
schema:
$ref: '#/components/schemas/TransformationExecution'
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/APIErrorResponse'
parameters:
- in: path
name: id
schema:
type: string
description: Transformation ID
required: true
- in: path
name: execution_id
schema:
type: string
description: Execution ID
required: true
components:
securitySchemes:
bearerAuth:
type: http
scheme: bearer
basicAuth:
type: http
scheme: basic
schemas:
TransformationExecutionPaginatedResult:
type: object
properties:
pagination:
$ref: '#/components/schemas/SeekPagination'
count:
type: integer
models:
type: array
items:
$ref: '#/components/schemas/TransformationExecution'
additionalProperties: false
OrderByDirection:
anyOf:
- enum:
- asc
- enum:
- desc
- enum:
- ASC
- enum:
- DESC
Operators:
type: object
properties:
gt:
type: string
format: date-time
nullable: true
gte:
type: string
format: date-time
nullable: true
le:
type: string
format: date-time
nullable: true
lte:
type: string
format: date-time
nullable: true
any:
type: boolean
all:
type: boolean
additionalProperties: false
APIErrorResponse:
type: object
properties:
code:
type: string
description: Error code
status:
type: number
format: float
description: Status code
message:
type: string
description: Error description
data:
type: object
properties: {}
nullable: true
required:
- code
- status
- message
additionalProperties: false
description: Error response model
TransformationExecution:
type: object
properties:
id:
type: string
transformed_event_data_id:
type: string
nullable: true
original_event_data_id:
type: string
transformation_id:
type: string
team_id:
type: string
description: ID of the project
webhook_id:
type: string
description: ID of the associated connection (webhook)
log_level:
$ref: '#/components/schemas/TransformationExecutionLogLevel'
logs:
type: array
items:
$ref: '#/components/schemas/ConsoleLine'
updated_at:
type: string
format: date-time
created_at:
type: string
format: date-time
original_event_data:
$ref: '#/components/schemas/ShortEventData'
transformed_event_data:
$ref: '#/components/schemas/ShortEventData'
issue_id:
type: string
nullable: true
required:
- id
- original_event_data_id
- transformation_id
- team_id
- webhook_id
- log_level
- logs
- updated_at
- created_at
additionalProperties: false
Transformation:
type: object
properties:
id:
type: string
description: ID of the transformation
team_id:
type: string
description: ID of the project
name:
type: string
description: A unique, human-friendly name for the transformation
code:
type: string
description: JavaScript code to be executed
encrypted_env:
type: string
nullable: true
x-docs-hide: true
iv:
type: string
nullable: true
x-docs-hide: true
env:
type: object
properties: {}
additionalProperties:
type: string
nullable: true
description: Key-value environment variables to be passed to the transformation
x-docs-force-simple-type: true
updated_at:
type: string
format: date-time
description: Date the transformation was last updated
created_at:
type: string
format: date-time
description: Date the transformation was created
required:
- id
- team_id
- name
- code
- updated_at
- created_at
additionalProperties: false
SeekPagination:
type: object
properties:
order_by:
anyOf:
- type: string
- type: array
items:
type: string
dir:
anyOf:
- $ref: '#/components/schemas/OrderByDirection'
- type: array
items:
$ref: '#/components/schemas/OrderByDirection'
limit:
type: integer
prev:
type: string
next:
type: string
additionalProperties: false
TransformationExecutorOutput:
type: object
properties:
request_id:
type: string
nullable: true
transformation_id:
type: string
nullable: true
execution_id:
type: string
nullable: true
log_level:
$ref: '#/components/schemas/TransformationExecutionLogLevel'
request:
type: object
properties:
headers:
anyOf:
- type: string
- type: object
properties: {}
additionalProperties:
nullable: true
nullable: true
path:
type: string
query:
anyOf:
- type: object
properties: {}
additionalProperties: false
nullable: true
- type: string
nullable: true
parsed_query:
anyOf:
- type: string
nullable: true
- type: object
properties: {}
additionalProperties: false
nullable: true
body:
anyOf:
- type: string
nullable: true
- type: object
properties: {}
additionalProperties: false
nullable: true
required:
- path
additionalProperties: false
nullable: true
console:
type: array
items:
$ref: '#/components/schemas/ConsoleLine'
nullable: true
required:
- log_level
additionalProperties: false
ConsoleLine:
type: object
properties:
type:
type: string
enum:
- error
- log
- warn
- info
- debug
message:
type: string
required:
- type
- message
additionalProperties: false
ShortEventData:
type: object
properties:
path:
type: string
description: Request path
query:
type: string
nullable: true
description: Raw query param string
parsed_query:
anyOf:
- type: string
nullable: true
- type: object
properties: {}
nullable: true
description: JSON representation of query params
headers:
anyOf:
- type: string
- type: object
properties: {}
additionalProperties:
type: string
nullable: true
nullable: true
description: JSON representation of the headers
body:
anyOf:
- type: string
- type: object
properties: {}
- type: array
items: {}
nullable: true
description: JSON or string representation of the body
is_large_payload:
type: boolean
nullable: true
description: Whether the payload is considered large payload and not searchable
required:
- path
- query
- parsed_query
- headers
- body
additionalProperties: false
nullable: true
description: Request data
TransformationPaginatedResult:
type: object
properties:
pagination:
$ref: '#/components/schemas/SeekPagination'
count:
type: integer
models:
type: array
items:
$ref: '#/components/schemas/Transformation'
additionalProperties: false
TransformationExecutionLogLevel:
type: string
enum:
- debug
- info
- warn
- error
- fatal
description: The minimum log level to open the issue on