Third Party Routing Overview

Via Hookdeck, you can connect your third-party services together by routing events between them. Third-party routing refers to the process of receiving webhooks or API calls from one service and forwarding them to another, often with modifications or filtering along the way. Hookdeck provides the necessary features to securely and reliably send events between your services.

Third party routing infrastructure

Skip to the Quickstart ->

A practical example on how to get started using Github and Twillio as examples.

With Hookdeck you can:

  • Receive HTTP requests and webhooks from any of your services
  • Transform and format the payload and headers of the events
  • Filter events by payload and header
  • Route events to one or more services
  • Set configurable retry policies
  • Get visibility into the delivery status of your events
  • Monitor and alert on the health of your event delivery

How to use Hookdeck for third-party routing

This guide provides a common approach to using Hookdeck for routing events between third-parties and covers a core subset of potential functionality:

  1. Configuring your sources, destinations and connections
  2. Transforming your events
  3. Filtering and routing your events
  4. Security and authentication mechanisms
  5. Handling callbacks
  6. Error handling, alerting and monitoring

Understanding Sources, Destinations, and Connections

Hookdeck acts as an intermediary between your third-party services. To route events between services, you need to define Source , Destination and configure Connection between them.

Sources as third-party webhooks

A Source represents a service that sends webhooks to Hookdeck. For each Source, you will be provided with a unique Webhook URL that you can use to receive webhooks from a third-party service. Typically, Sources will be named after the service that sends the webhooks, such as github or stripe.

Destinations as third-party APIs

A Destination represents a service that receives events from Hookdeck. A Destination is the HTTP URL where Hookdeck will deliver the Events. Typically, the Destination is an API endpoint of another third-party service.

Destinations in Hookdeck offer several configuration options to ensure compatibility and security when interfacing with third-party APIs:

Changing the HTTP Method

You can configure a destination to use a specific HTTP method when delivering events. This allows you to match the requirements of the receiving API. Hookdeck supports GET POST PUT PATCH DELETE HTTP methods.

Authentication Schemes

Hookdeck supports various authentication methods for destinations, allowing you to securely connect with a wide range of third-party APIs:

  • Basic Auth: Uses username and password for authentication.

  • API Key: Sends an API key in a custom header or query parameter.

  • Bearer Token: Uses the standard HTTP Authorization header with a Bearer token.

  • OAuth 2.0: Supports OAuth 2.0 authentication flow, allowing secure authorization with third-party services that implement this standard.

Connections for event routing

A Connection consists of a Source, a Destination and set of optional rules. It defines the flow of the Event , from receipt through to delivery. When a webhook is received, Hookdeck will create a new Event for each eligible Connection.

Rules allow you to configure the behavior of Events received on the Connection, including transformations, filters, and retries.

Formatting events into API calls

Transformation rules allow you to modify the payload of an event before it gets delivered to a destination. This feature is crucial when connecting third-party services, as it allows you to:

  • Convert data formats between services (e.g., from XML to JSON)
  • Map fields from one service's schema to another
  • Add or remove fields as required by the destination service

For example, you could use a transformation to convert a GitHub webhook payload into the format expected by Slack for posting messages. Here's an example of such a transformation:

addHandler("transform", (request, context) => {
  const githubPayload = request.body;

  // Extract relevant information from GitHub payload
  const repoName = githubPayload.repository.full_name;
  const pullRequestTitle = githubPayload.pull_request.title;
  const pullRequestUrl = githubPayload.pull_request.html_url;
  const action = githubPayload.action;

  // Create Slack message payload and update the event body
  request.body = {
    text: `New GitHub Activity!`,
    blocks: [
      {
        type: "section",
        text: {
          type: "mrkdwn",
          text: `*Pull Request ${action} in ${repoName}*\n<${pullRequestUrl}|${pullRequestTitle}>`,
        },
      },
    ],
  };

  return request;
});

This transformation does the following:

  1. Parses the incoming GitHub webhook payload.
  2. Extracts relevant information about a pull request event (repository name, pull request title, URL, and action).
  3. Constructs a new payload formatted for Slack's API, including a message with a link to the pull request.
  4. Updates the request body with the new Slack-formatted payload.
  5. Updates the content-type header to application/json as required by Slack's API.

By applying this transformation, you can automatically convert GitHub pull request events into nicely formatted Slack messages.

Filtering and routing events

Filter rules allow you to deliver Events matching specific criteria to a Destination. This is particularly useful when dealing with third-party services that send a wide variety of event types.

Filters can be used in conjunction with multiple Destinations to route different types of events to different services. For example, you could route GitHub pull request events to one service and push events to another.

Here's a simple example of a filter rule that only allows pull request events from a specific repository:

{
  "repository": {
    "full_name": "username/specific-repo"
  },
  "pull_request": {
    "$exist": true
  }
}

This filter would only allow events that have a repository.full_name matching "username/specific-repo" and have a pull_request object in the payload. This effectively filters for pull request events from a specific repository.

Security and authentication

When routing events between third-party services you must configure your source and destination to authenticate the requests.

  • Source Authentication: Verify the authenticity of incoming requests using methods like HMAC signatures or API keys.
  • Destination Authentication: Securely authenticate with destination services using various methods including API keys, OAuth tokens, or custom authentication schemes.

Handling callbacks

When routing events between third-party services, you might need to know the result of the event delivery or perform additional actions based on the outcome. While Hookdeck is not a workflow or step functions engine, it does provide the events.successful webhook notification that can be used to receive a callback when an event is successfully delivered to its destination and trigger follow-up actions. This feature is particularly useful for:

  • Confirming that events have been properly routed and processed
  • Triggering follow-up actions
  • Maintaining an audit trail of successful event deliveries

Set a webhook notification ->

Track problems and communicate resolutions with your team.

Error handling and monitoring

Hookdeck provides comprehensive tools for monitoring your event routing and recovering from errors:

Automatic retries

The retries rule lets you configure automatic retries for Events that do not receive a successful response from your Destination. This is crucial when dealing with third-party services that may experience temporary downtime.

Issues for problem resolution

Issues allow you to track and resolve problems that occur within your event routing. You can set Issue Triggers to open issues when certain criteria are met, such as when an event has exhausted its automatic retries or fails to be delivered.

Metrics for monitoring

Metrics provide insight into your Requests, Events, and Attempts. They are available in the dashboard and can be exported to your observability platform. These metrics are crucial for understanding the performance and reliability of your event routing setup.

Limitations

Synchronous responses

Hookdeck does not support synchronous responses to incoming request. If your third-party service requires a synchronous response from your destinations you will need to implement a separate mechanism to handle this such as webhook event.successful notifications.

Transformations do not support I/O operations

Transformations in Hookdeck are designed to be lightweight and fast. They do not support I/O operations such as making HTTP requests or reading from external sources. If you need to perform these operations, you should use a separate service or function to handle them. Set that service as a destination for the event and use a transformation to prepare the payload for it.

Workflow management

Hookdeck is not a workflow engine. While you can use Hookdeck to route events between services, it does not provide the ability to orchestrate complex workflows or manage state between services. If you require this functionality, you may need to use a separate workflow management tool.

Next -> Quickstart