HookFlow

Transforming Webhooks

HookFlow allows you to transform webhook payloads before they're delivered to your destinations. This guide explains how to use transformation rules to modify, enrich, or simplify webhook data.

Why Transform Webhooks?

There are several reasons you might want to transform webhook payloads:

  • Format Compatibility: Convert webhook data to match the format expected by your application
  • Data Simplification: Remove unnecessary fields to reduce payload size
  • Data Enrichment: Add additional information or context to the payload
  • Field Renaming: Rename fields to match your application's naming conventions
  • Data Normalization: Standardize data formats across different webhook providers

How Transformations Work

Transformations in HookFlow are applied on a per-destination basis. This means:

  • Each destination can have its own set of transformation rules
  • Rules are applied in the order they are defined
  • Transformations occur after filtering but before delivery
  • The original webhook payload is preserved in logs for reference

Original Webhook Payload

Filter Rules Applied

Transform Rules Applied

Delivered to Destination

Types of Transformations

HookFlow supports several types of transformation operations:

Add Field

Add a new field to the webhook payload with a specified value.

Example:

Add field "processed_by" with value "hookflow"

Remove Field

Remove a field from the webhook payload.

Example:

Remove field "sensitive_data"

Rename Field

Change the name of a field while preserving its value.

Example:

Rename field "evt_type" to "event_type"

Modify Value

Change the value of an existing field.

Example:

Set field "status" to value "processed"

Copy Value

Copy a value from one field to another.

Example:

Copy value from "data.id" to "id"

Format Value

Format a field's value (e.g., date formatting, string operations).

Example:

Format "created_at" as ISO date string

Configuring Transformations

You can configure transformation rules when creating or editing a destination:

  1. Navigate to the source that contains the destination
  2. Click on the destination to expand its settings
  3. Scroll to the "Transform Rules" section
  4. Click "Add Transform Rule" to create a new rule
  5. Configure the rule with the following settings:
    • Operation: The type of transformation to perform
    • Path: The JSON path to the field you want to transform
    • Value: The new value or target path (depending on the operation)
  6. Add additional rules as needed (they will be applied in order)
  7. Save your changes

Note: Transformation rules are applied in the order they are defined. If you have multiple rules that affect the same field, the later rules will operate on the result of the earlier rules.

JSON Path Syntax

HookFlow uses JSON path syntax to specify which fields to transform. Here's a quick reference:

SyntaxDescriptionExample
fieldTop-level fieldid, type, created_at
parent.childNested fielddata.customer.email
array[0]Array element by indexitems[0].price
field\.with\.dotsField name with dotsmetadata.user\.id

Example Transformations

Here are some common transformation scenarios and how to implement them:

Flattening Nested Data

Move nested fields to the top level for easier access.

Original Payload:

{
  "event": "payment.succeeded",
  "data": {
    "payment": {
      "id": "pay_123",
      "amount": 1000,
      "currency": "usd"
    }
  }
}

Transform Rules:

  1. Copy value from "data.payment.id" to "payment_id"
  2. Copy value from "data.payment.amount" to "amount"
  3. Copy value from "data.payment.currency" to "currency"

Result:

{
  "event": "payment.succeeded",
  "data": {
    "payment": {
      "id": "pay_123",
      "amount": 1000,
      "currency": "usd"
    }
  },
  "payment_id": "pay_123",
  "amount": 1000,
  "currency": "usd"
}

Removing Sensitive Data

Remove sensitive information before forwarding webhooks.

Original Payload:

{
  "customer": {
    "id": "cus_123",
    "email": "user@example.com",
    "payment_method": {
      "card": {
        "last4": "4242",
        "exp_month": 12,
        "exp_year": 2025
      }
    }
  }
}

Transform Rules:

  1. Remove field "customer.email"
  2. Remove field "customer.payment_method.card"

Result:

{
  "customer": {
    "id": "cus_123",
    "payment_method": {}
  }
}

Normalizing Data Formats

Standardize data formats across different webhook providers.

Original Payload (Stripe):

{
  "type": "charge.succeeded",
  "created": 1647532800,
  "data": {
    "object": {
      "id": "ch_123",
      "amount": 2000
    }
  }
}

Transform Rules:

  1. Add field "provider" with value "stripe"
  2. Rename field "type" to "event_type"
  3. Format "created" as ISO date string
  4. Copy value from "data.object.id" to "transaction_id"
  5. Copy value from "data.object.amount" to "amount_cents"
  6. Add field "amount_dollars" with value from "amount_cents" divided by 100

Result:

{
  "provider": "stripe",
  "event_type": "charge.succeeded",
  "created": "2022-03-17T12:00:00Z",
  "data": {
    "object": {
      "id": "ch_123",
      "amount": 2000
    }
  },
  "transaction_id": "ch_123",
  "amount_cents": 2000,
  "amount_dollars": 20
}

Best Practices

Follow these best practices when configuring transformations:

  • Keep it simple: Use the minimum number of transformations needed
  • Test thoroughly: Verify transformations with sample webhooks before deploying
  • Be careful with removals: Don't remove fields that might be needed later
  • Consider performance: Complex transformations on large payloads may impact delivery time
  • Use descriptive names: When adding or renaming fields, use clear and consistent naming

Next Steps

Now that you understand how to transform webhooks, explore these related topics: