Routing functions

Routing functions allow you to dynamically direct messages to different destinations based on the content of the message. This is useful for:

• Interacting with REST APIs which assign each record its own resource path
• Using different HTTP methods based on the change action
• Implementing custom routing logic based on record contents

Currently, routing functions are available for HTTP webhook destinations. Routing for other sinks is planned but not yet generally available.

​

How routing functions work

When you create a routing function, you define an Elixir function that returns routing information. Sequin will use this information to determine the destination for each message.

For each message, your routing function receives the same parameters as a transform function and must return a map containing the sink-specific routing information:

def route(action, record, changes, metadata) do
  %{
    method: "POST",  # HTTP method to use
    endpoint_path: "/api/users/#{record["id"]}"  # appended to base URL
  }
end

In general, some details of how the message is processed will be static and fixed by the sink. Routing functions enable you to customize the behavior of a sink, but they are not intended to replace the idea of multiple sinks where necessary. For example, for the HTTP Webhook sink, the base URL is a static property - this improves batching and enables other performance optimizations such as connection pooling and request pipelining.

​

Supported sinks

Currently, routing functions are supported by the following sinks:

​

HTTP Webhook sink

For HTTP webhooks, your routing function must return a map with these keys:

The endpoint_path you specify will be appended to the base URL of your webhook endpoint. For example, if your webhook endpoint is https://api.example.com and your routing function returns endpoint_path: "/users/123", the message will be sent to https://api.example.com/users/123.

​

Common routing patterns

​

Routing to REST APIs

Route messages to RESTful endpoints based on record ID and action:

def route(action, record, changes, metadata) do
  endpoint_path = "/api/users/#{record["external_id"]}"

  method = case action do
    "insert" -> "POST"
    "update" -> "PUT"
    "delete" -> "DELETE"
    _ -> "POST"
  end

  %{
    method: method,
    endpoint_path: endpoint_path
  }
end

​

Content-based routing

Route messages based on their content:

def route(action, record, changes, metadata) do
  # Route high-priority messages to a different endpoint
  if record["priority"] == "high" do
    %{
      method: "POST",
      endpoint_path: "/api/priority-events"
    }
  else
    %{
      method: "POST",
      endpoint_path: "/api/events"
    }
  end
end

​

Testing routing functions

When creating or editing a routing function, you can test it with real data from your database. Sequin will capture recent events and show you the effective routing parameters for each message.

“Effective” means that Sequin will show the routing parameters that will actually be used downstream, inclusive of any defaulting or validation which happens after your routing function runs.

​

Limitations and considerations

• Currently, routing functions are only available for HTTP webhook destinations.
• Routing can impact batching if your routing function generates different destinations for each message.

​

Related