Subscriptions - Sailhouse

Subscriptions are the way events are consumed across your application. There are two types of subscription available, each with very different methods of using and use-cases.

Push

A push subscription sends a POST request to a specific endpoint when it recieves an event, with the request body being the event data. Sailhouse expects a 200 OK response within 5 seconds of it being sent, otherwise it will count the attempt as failed and retry

Retries

Sailhouse will attempt to deliver an event every 5 minutes after the first failure up to 5 times. As soon as a 200 OK is recieved, the event is counted as acknowledged. If an event isn’t acknowledged in this time frame, it is counted as a dead letter

Dead Letters

“Dead letters” are events that were failed to be delivered, and so are given a status which indicates the platform will not attempt to deliver them until user (ie, developer) intervention. However, any new events Sailhouse will attempt to deliver as usual. When the upstream issue preventing processing of events has been fixed, you can clear the dead letters 1-by-1 or all at once, which will re-insert them into the queue for processing.

Unlike new events, events from the dead letter queue will instantly be returned to the dead letter queue on failure, with no retries attempted.

Pull

Pull subscriptions require the consuming application to request the events ad-hoc. Think a billing cycle that runs every 6 hours, or an activity summariser that counts the number of actions within a week. They allow you to build processing-heavy workflows that only consume new data extremely easily. Instead of having to perform a complex, expensive query on a database, you just pull all the new events through.

Subscription Filters

Subscription filters is one of the developer-focused features of the platform. When it comes to building an event-driven system, the decision of making a generic or narrow-scope topic can often have massive downstream impact on the simplicity of building new features. If it’s too generic, many consumers will recieve events they don’t care about. If it’s too narrow in scope, you’ll have several events being sent as part of the same operation, making it hard to understand the flows and what triggers where. Subscription filters allow you to keep your topics generic, while reducing noise and cost. You can instruct subscriptions to only care about certain events, dynamically. It keeps your code simple, and your costs down.

The full power of subscription filters lies beyond key = value pairs, and this will be something we expand on as the platform develops.

Filter Path

The filter path is the simple JSON path to the property you want to filter on.

Event	Path
`user-created`	`user.type`
`order-created`	`order.address.country`
`application-updated`	`application.status`

Metadata

You can read from the metadata of the event by prefixing the path with _metadata., for example _metadata.source.

Arrays

If the path points to an array, the subscription will trigger if the filter value matches any of the elements in the array. For example, if the path is roles, and the filter value is admin, the subscription will trigger if the event has the property like so:

{
  "roles": ["admin", "user"]
}

Filter Value

The filter value is the value for a subscription to match on, following the examples above.

Value	Example
`pro`	Create the customer on stripe and start their trial.
`UK`	For the UK, you may need to run extra logic for imports and taxes.
`rejected`	When an application is rejected, we should email the candidate. Not all updates need contact.

Advanced Filters

For more complex filtering scenarios, you can combine multiple filter conditions using logical operators.

Multiple Conditions

filter: {
  filters: [
    { path: "user.type", condition: "equals", value: "premium" },
    { path: "user.status", condition: "not_equals", value: "inactive" }
  ],
  operator: "and"
}

Available Conditions

Condition	Description	Example
`equals`	Exact match (default)	`user.type` equals `premium`
`not_equals`	Does not match	`status` not equals `inactive`

Logical Operators

Operator	Description
`and`	All conditions must match
`or`	At least one condition must match

Rate Limiting and Deduplication

Subscriptions also support rate limiting and deduplication to control delivery behavior:

Rate Limit: Controls how frequently events are delivered (e.g., “100/h” for 100 per hour, “10/m” for 10 per minute)
Deduplication: Prevents duplicate deliveries within a specified time window (e.g., “5m” for 5 minutes, “1h” for 1 hour)

await client.admin.registerPushSubscription(
  "user-events",
  "premium-user-events",
  "https://api.example.com/webhooks/premium",
  {
    filter: {
      filters: [
        { path: "user.type", condition: "equals", value: "premium" },
        { path: "user.status", condition: "not_equals", value: "inactive" }
      ],
      operator: "and"
    },
    rate_limit: "50/h",
    deduplication: "10m"
  }
);

​Push

​Retries

​Dead Letters

​Pull

​Subscription Filters

​Filter Path

​Metadata

​Arrays

​Filter Value

​Advanced Filters

​Multiple Conditions

​Available Conditions

​Logical Operators

​Rate Limiting and Deduplication

Push

Retries

Dead Letters

Pull

Subscription Filters

Filter Path

Metadata

Arrays

Filter Value

Advanced Filters

Multiple Conditions

Available Conditions

Logical Operators

Rate Limiting and Deduplication