Warning

This project is currently in ALPHA. Features and documentation are subject to change.

View the roadmap

Open Source Event Destinations Infrastructure

Documentation · Report a bug · Request a feature

Outpost is a self-hosted and open-source infrastructure that enables event producers to add Event Destinations to their platform with support for destination types such as Webhooks, Hookdeck Event Gateway, Amazon EventBridge, AWS SQS, AWS SNS, GCP Pub/Sub, RabbitMQ, and Kafka.

Learn more about Event Destinations in the Event Destinations Manifesto.

Architecture

See the Outpost Concepts for more information.

Features

• Event topics and topics-based subscriptions: Supports the common publish and subscription paradigm to ease adoption and integration into existing systems.
• Publish events via the API or a queue: Publish events using the Outpost API or configure Outpost to read events from a publish queue.
• At least once delivery guarantee: Messages are guaranteed to be delivered at least once and never lost.
• Event fanout: A message is sent to a topic is replicated and sent to multiple endpoints. This allows for parallel processing and asynchronous event notifications.
• User portal: Allow customers to view metrics, manage, debug, and observe their event destinations.
• Automatic and manual retries: Configure retry strategies for event destinations and manually trigger event delivery retries via the API or user portal.
• Multi-tenant support: Create multiple tenants on a single Outpost deployment.
• User alerts: Allow customers to manage event delivery alerts.
• OpenTelemetry: OTel standardized traces, metrics, and logs.
• Event destination types: Out of the box support for Webhooks, Hookdeck Event Gateway, Amazon EventBridge, AWS SQS, AWS SNS. GCP Pub/Sub, RabbitMQ, and Kafka.
• Webhook best practices: Opt-out webhook best practices, such as headers for idempotency, timestamp and signature, and signature rotation.

See the Outpost Features for more information.

Quickstart

Ensure you have Docker installed.

Clone the Outpost repo:

git clone https://github.com/hookdeck/outpost.git

Navigate to outpost/examples/docker-compose/:

cd outpost/examples/docker-compose/

Create a .env file from the example:

cp .env.example .env

Update the $API_KEY value within the new .env file.

Start the Outpost dependencies and services:

docker-compose -f compose.yml -f compose-rabbitmq.yml -f compose-postgres.yml up

Check the services are running:

curl localhost:3333/api/v1/healthz

Wait until you get a OK% response.

Create a tenant with the following command, replacing $TENANT_ID with a unique identifier such as "your_org_name", and the $API_KEY with the value you set in your .env:

Tip

You can use shell variables to store the tenant ID and API key for easier use in the following commands:

TENANT_ID=your_org_name
API_KEY=your_api_key
URL=your_webhook_url

curl --location --request PUT "localhost:3333/api/v1/$TENANT_ID \
--header 'Authorization: Bearer $API_KEY'

Run a local server exposed via a localtunnel or use a hosted service such as the Hookdeck Console to capture webhook events.

Create a webhook destination where events will be delivered to with the following command. Again, replace $TENANT_ID and $API_KEY. Also, replace $URL with the webhook destinations URL:

curl --location "localhost:3333/api/v1/$TENANT_ID/destinations" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer $API_KEY" \
--data '{
    "type": "webhook",
    "topics": ["*"],
    "config": {
        "url": "'"$URL"'"
    }
}'

Publish an event, remembering to replace $API_KEY and $TENANT_ID:

curl --location "localhost:3333/api/v1/publish" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer $API_KEY" \
--data '{
    "tenant_id": "'"$TENANT_ID"'",
    "topic": "user.created",
    "eligible_for_retry": true,
    "metadata": {
        "meta": "data"
    },
    "data": {
        "user_id": "userid"
    }
}'

Check the logs on your server or your webhook capture tool for the delivered event.

Get an Outpost portal link for the tenant:

curl "localhost:3333/api/v1/$TENANT_ID/portal" \
--header "Authorization: Bearer $API_KEY"

The response will look something like the following:

{ "redirect_url": "http://localhost:3333?token=$TOKEN" }

The token value is an API-generated JWT.

Open the redirect_url link to view the Outpost portal.

Continue to use the Outpost API or the Outpost portal to add and test more destinations.

Documentation

• Get Started
• Overview
• Features
• Guides
• References
  • API Reference
  • Configuration Reference

Contributing

See CONTRIBUTING.

License

This repository contains Outpost, covered under the Apache License 2.0, except where noted (any Outpost logos or trademarks are not covered under the Apache License, and should be explicitly noted by a LICENSE file.)