Transform Event Payload Content-Type (e.g., x-www-form-urlencoded to JSON)

If your application's event handler or API endpoint is built to process application/json payloads, but a the services that generates the event sends the payload in a different format, you can use a Hookdeck Transformation to convert the payload to JSON.

How Hookdeck Handles Content Types

Hookdeck can ingest events with a variety of content types:

• text/plain
• text/xml
• application/json
• application/x-www-form-urlencoded
• application/xml
• application/*+json
• application/jwt
• application/x-ndjson
• multipart/form-data

While Hookdeck does not natively convert all of them to JSON, you can use transformations to perform the conversion yourself. The one exception is application/x-www-form-urlencoded, Hookdeck can automatically parse into a JSON object in the request.body when a transformation is run.

Step-by-Step Configuration in Hookdeck

1. Create a Connection : When creating a connection, you will configure a Source to receive events from your provider and a Destination where Hookdeck will send them.
2. Add a Transformation to the Connection:
   • Navigate to the Connection's settings and add a new transformation.
3. Implement the Transformation Script:
   • Write and apply your JavaScript transformation code. The logic will differ based on the incoming content type.
   • While transformations can be managed in the Dashboard, a better solution for automation and version control is to manage them via the Hookdeck API.

Example: application/x-www-form-urlencoded to JSON

Because Hookdeck automatically parses x-www-form-urlencoded data into a JSON object, the transformation is very simple. This code just updates the header.

addHandler('transform', (request, context) => {
  if (request.headers['content-type'] &&
      request.headers['content-type'].toLowerCase().includes('application/x-www-form-urlencoded')) {
    request.headers['content-type'] = 'application/json';
  }

  // Return the modified request
  return request;
});

Testing the Transformation

The Transformation UI in the Hookdeck Dashboard provides a feature for testing your code. You can select a recent event, or update a payload to the structure you want to test, and apply your transformation script to its payload to see the output in real-time, allowing for rapid iteration and debugging.

1. Send a Test Request: Use a tool like curl or Postman to send a POST request to your Hookdeck Source URL with the original Content-Type and payload format.
2. Check Hookdeck Events Log:
   • Inspect the Event for the relevant Connection.
   • Verify the incoming request has the original Content-Type and body.
   • Check the Attempt to your Destination to confirm the Content-Type is now application/json and the payload is the correctly structured JSON object.
3. Check Your Backend: Ensure your endpoint received and processed the JSON payload successfully.

Conclusion

Hookdeck Transformations provide a powerful way to decouple the producer of an event from the consumer. This means the consuming application does not need to be concerned with the content type of the event payload sent by the producer. By handling content-type conversions at the gateway, you can ensure that the consuming application or API endpoint receives event payloads in a consistent, expected format like application/json, simplifying your event-driven workflows.

Related Hookdeck Features & Documentation

Comprehensive Guide to Transformations ->

Learn all about writing transformation scripts.

Managing Connections ->

Where transformations are applied.

Using Event Logs for Debugging ->

Verify your transformation outputs.