Hookdeck

Hookdeck Transformations API

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.

Hookdeck Transformations API is one of 12 APIs that Hookdeck publishes on the APIs.io network, described by a machine-readable OpenAPI specification.

This API exposes 2 machine-runnable capabilities that can be deployed as REST, MCP, or Agent Skill surfaces via Naftiko and 1 JSON Schema definition.

Tagged areas include Transformations, Webhooks, and Event Gateways. The published artifact set on APIs.io includes API documentation, an OpenAPI specification, 2 Naftiko capability specs, and 1 JSON Schema.

GitHub OpenAPI

Documentation

📖
Documentation
https://hookdeck.com/docs/transformations

Specifications

⚙
OpenAPI
https://raw.githubusercontent.com/api-evangelist/hookdeck/refs/heads/main/openapi/hookdeck-transformations-api-openapi.yml

Schemas & Data

📊
JSONSchema
https://raw.githubusercontent.com/api-evangelist/hookdeck/refs/heads/main/json-schema/hookdeck-transformation-schema.json

Other Resources

🔗
NaftikoCapability
https://raw.githubusercontent.com/api-evangelist/hookdeck/refs/heads/main/capabilities/hookdeck-transformations.yaml
🔗
NaftikoCapability
https://raw.githubusercontent.com/api-evangelist/hookdeck/refs/heads/main/capabilities/hookdeck-transformations-author.yaml

OpenAPI Specification

hookdeck-transformations-api-openapi.yml Raw ↑ 
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: [email protected]
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