Run your Engines as a Webhook Service

This page explains how to run your Engine as a real webhook service, meaning it can receive bounties over HTTP, process them asynchronously, then send assertions back to PolySwarm.

Architecture (what runs where)

A typical webhook Engine has three moving parts:

Webhook HTTP server

Receives bounty events via HTTP POST
Verifies the request signature
Returns 202 Accepted quickly
Enqueues work for processing

Queue and broker

A message broker such as RabbitMQ
Connects the web server to the worker

Worker

Pulls jobs from the queue
Executes your analyzer logic
Posts the assertion back to the marketplace using the provided response endpoint

Prerequisites

Docker and docker compose (recommended for local development)
A broker URL configured for both the server and the worker

Required configuration

Both the HTTP server and worker must share the broker configuration, commonly set via an environment variable such as:

PSENGINE_BROKER_URL (template default example uses AMQP)
- example: amqp://user:password@rabbitmq:5672

You will also configure a webhook shared secret (used to validate signatures).

Running locally (recommended path)

Use the template repo docker compose example to run:

Broker
Webhook server
Worker
Optional integration helper service for local testing

This gives you the closest behavior to production without hand-installing RabbitMQ and process managers.

If you support a non-docker path, document it as an alternative, but keep docker as the default for Engine partners.

Webhook security requirements

Validate request signatures

Your webhook server should verify that incoming requests are truly from PolySwarm. This is typically done via an HMAC signature header using a shared secret configured in your Team account webhook.

Requirements:

Reject unsigned requests
Reject invalid signatures
Do not run analysis for invalid requests

Return quickly

Your HTTP server should not block while scanning.

Return 202 Accepted immediately after validation
Enqueue work for the worker to process

Replay protection

If your webhook includes a delivery id or request id, log it and ensure duplicates do not trigger duplicate processing.

Operational expectations (development)

Log at least: request received, request validated, job queued, analysis completed, assertion posted
Enforce timeouts on any external tools
Ensure crashes do not take down both the server and worker
Prefer a small, stable set of environment variables over hardcoding values