Webhooks
Receive Algenta events by webhook — async job callbacks, trigger notifications, and decision-execution dispatch — verify delivery with a test POST, and receive inbound GitHub App events.
Webhooks let Algenta push events to your endpoints instead of you polling for them. The engine sends outbound webhooks in three situations — when an async job finishes, when a trigger fires, and when a trigger dispatches a decision for execution — and it exposes a test endpoint so you can confirm your receiver works before you rely on it. In the other direction, the GitHub App delivers inbound events to the engine to start automated fixes.
Every outbound call is guarded by the engine's egress policy: a destination your deployment has not allowed is logged and skipped rather than sent. Use HTTPS endpoints in production. All API routes below require Authorization: Bearer $ALGENTA_API_KEY.
Outbound: async job callbacks
Submit a long-running simulation as an async job with a callback_url, and the engine POSTs the completed result to that URL when the job finishes — no polling required.
POST /v1/jobs
curl -sS -X POST "https://api.algenta.ai/v1/jobs" \
-H "Authorization: Bearer $ALGENTA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"callback_url": "https://example.com/algenta/webhook",
"request": {
"mode": "auto",
"scenario": {
"variables": { "revenue": { "low": 80000, "high": 200000 } },
"objective": "maximize_net_value"
},
"runs": 50000,
"seed": 42
}
}'import os
from decision_engine import AlgentaClient
client = AlgentaClient(
api_key=os.environ["ALGENTA_API_KEY"],
base_url="https://api.algenta.ai",
)
job = client.submit_job(
{
"mode": "auto",
"scenario": {
"variables": {"revenue": {"low": 80000, "high": 200000}},
"objective": "maximize_net_value",
},
"runs": 50000,
"seed": 42,
},
callback_url="https://example.com/algenta/webhook",
)
print(job["job_id"], job["poll_url"])When the job completes, your endpoint receives a signed POST. The body carries the event and result; the headers carry the HMAC signature you verify against your signing secret:
X-Webhook-Signature
sha256=... HMAC of the raw body — verify this before trusting the payload.
X-Webhook-Event
The event name (for example job.completed).
X-Job-Id
The job id, for correlation.
Outbound: trigger notifications and decision execution
A trigger can attach two webhook URLs. When it fires, the engine POSTs a lightweight notification to webhook_url, and — when auto_execute is on — the full decision plan to execution_webhook_url for an automated actuator to run.
The notification payload summarizes the fire:
The execution payload carries the actionable decision plan as a decision.execute event, so a downstream service can act on it:
Verify delivery with a test POST
Before you wire a real callback, confirm your endpoint accepts the engine's requests. The test endpoint sends a single webhook.test payload to any URL and returns the delivery outcome — no retries.
POST /v1/webhooks/test
Inbound: the GitHub App
Webhooks also flow the other way. When you install the Algenta GitHub App, GitHub delivers repository events to the engine's inbound receiver, POST /webhooks/github. That route is the one public, unauthenticated endpoint: it verifies GitHub's HMAC signature (X-Hub-Signature-256), dedupes the delivery by its id, and returns 202 within seconds, then runs the fix pipeline asynchronously. You do not call it yourself — GitHub does. To connect it and see which events start a fix, follow the install stepper in Fix a repository.
Next steps
Last updated
Was this helpful?