Webhooks push each event to your server the moment it happens: a task succeeds, waits for an answer, fails. They are the right way to get results in production.
Create an endpoint
An endpoint is an https address on your server, the events it wants, and its own signing secret. You can have up to 16 per mode.
curl https://api.hapti.dev/v1/webhooks/endpoints \
-H "Authorization: Bearer $HAPTI_KEY" \
-H "Content-Type: application/json" \
-d '{"url": "https://api.example.com/hooks/hapti", "events": ["task.succeeded", "task.failed", "task.waiting"], "description": "Production"}'{
"id": "we_0e47caf33717b1a8",
"object": "webhook_endpoint",
"url": "https://api.example.com/hooks/hapti",
"events": [
"task.succeeded",
"task.failed",
"task.waiting"
],
"description": "Production",
"enabled": true,
"disabled_reason": null,
"disabled_at": null,
"failing_since": null,
"last_success_at": null,
"headers": {},
"mode": "test",
"secret": "whsec_0f9c3a…",
"previous_secret_expires_at": null,
"created_at": "2026-11-22T18:40:56.225Z"
}Keep the secret: it is shown here in full. You can reveal it later with GET /v1/webhooks/endpoints/{id}/secret. Endpoints can also be managed in the console, under Developers, Webhooks, where Send a test delivers a signed ping event at once and shows the answer of your server.
events takes event types, a family such as user.*, or ["*"] for every event, including the ones added later.
Event types
| Event | When |
|---|---|
task.created | A task was created. |
task.paused | A live task waits for credit. |
task.waiting | The agent asks a question or an approval. |
task.succeeded | A task succeeded. |
task.failed | A task failed. |
task.cancelled | A task was cancelled. |
batch.finished | Every task of a batch is over. |
email.received | An email reached a person's inbox. |
sms.received | A text reached a person's number. |
user.account_connected | A person connected an account. |
user.account_removed | A person removed an account. |
user.forward_started | A person started forwarding mail. |
user.forward_stopped | A person stopped forwarding mail. |
user.memory_forgotten | A person erased what the agent kept. |
ping | A test sent from the console or the API. |
The payload
Every delivery is a POST with a JSON event. The same event, with the same id, goes to every endpoint that wants it.
{
"id": "evt_c3b9a22cc8666f754e930055",
"object": "event",
"type": "task.succeeded",
"api_version": "2026-11-22",
"created_at": "2026-11-22T18:40:56.191Z",
"mode": "test",
"data": {
"id": "tsk_9a96d9052acef545",
"object": "task",
"batch": null,
"schedule": null,
"mode": "test",
"status": "succeeded",
"paused": null,
"level": "standard",
"price_cents": 0,
"starting_price_cents": 10,
"billed": false,
"user": "customer_42",
"url": "https://portal.example.com/claims",
"goal": "Declare the water damage claim and give me the claim number.",
"input": {
"data": {
"contract": "AX-4471",
"date": "2026-11-20"
},
"files": []
},
"pending": null,
"learn": true,
"used_recipe": null,
"template": null,
"created_by": {
"type": "key",
"id": "key_d160ed300d0cf627",
"hint": "hp_test_7eF…ZD9D",
"name": "default test key",
"owner_email": null
},
"recipe_chosen": null,
"recipe": null,
"dispute": null,
"result": {
"answer": "The claim is declared. Claim number SIN-2026-118.",
"data": {
"claim_number": "SIN-2026-118"
}
},
"files": [],
"usage": {
"steps": 14
},
"created_at": "2026-11-22T18:40:56.170Z",
"finished_at": "2026-11-22T18:40:56.190Z"
}
}| Header | Value |
|---|---|
Hapti-Signature | t= the time, then one v1= signature per valid secret |
Hapti-Event | The event type |
Hapti-Event-Id | The event id. Use it to ignore an event you already handled |
Hapti-Delivery | The delivery id, as shown in the console and the API |
Hapti-Attempt | 1 for the first try, then 2, 3 and so on |
Verify the signature
Always check that a delivery comes from Hapti before you trust it. The signature is an HMAC SHA-256 of the time, a dot and the raw body, with your endpoint secret. Use the raw body exactly as received, before any JSON parsing.
import express from 'express';
import Hapti from 'hapti-sdk';
const app = express();
app.post('/hooks/hapti', express.raw({ type: 'application/json' }), async (req, res) => {
const ok = await Hapti.verifyWebhook(req.body, req.get('Hapti-Signature'), process.env.HAPTI_WEBHOOK_SECRET);
if (!ok) return res.status(400).end();
const event = JSON.parse(req.body);
res.status(200).end();
await handle(event);
});import os
from flask import Flask, request
from hapti import verify_webhook
app = Flask(__name__)
@app.post("/hooks/hapti")
def hapti_hook():
raw = request.get_data()
if not verify_webhook(raw, request.headers.get("Hapti-Signature"), os.environ["HAPTI_WEBHOOK_SECRET"]):
return "", 400
handle(request.get_json())
return "", 200import { createHmac, timingSafeEqual } from 'node:crypto';
function verify(raw, header, secret, tolerance = 300) {
const parts = header.split(',').map((p) => p.split('='));
const t = Number(parts.find(([k]) => k === 't')?.[1]);
if (!t || Math.abs(Date.now() / 1000 - t) > tolerance) return false;
const mac = createHmac('sha256', secret).update(`${t}.${raw}`).digest('hex');
return parts.filter(([k]) => k === 'v1').some(([, v]) => v.length === mac.length && timingSafeEqual(Buffer.from(v), Buffer.from(mac)));
}The libraries refuse a signature older than 5 minutes, which stops replays. While a secret is being rotated, a delivery carries two v1 signatures: accept the delivery when any of them matches.
Retries
Answer with any 2xx status within 15 seconds. Anything else is retried, up to 9 attempts over about three days: at once, then after 1 minute, 5 minutes, 30 minutes, 2 hours, 6 hours, 12 hours, 24 hours and 24 hours, with a little random spread. Every attempt is kept with its status, time and answer, in the console and in GET /v1/webhooks/deliveries/{id}.
- Deliveries to one endpoint keep their order. A slow or failing endpoint never delays the others.
- When your server answers 5xx, 429 or nothing, its endpoint rests 30 seconds before the next try.
- An event can arrive more than once, for example when your server timed out after handling it. Use
Hapti-Event-Idto handle each event once. - Answer fast and do the work afterwards, in a queue if it is long.
When an endpoint keeps failing
An endpoint that has failed for three days without a single success is paused, its waiting deliveries are closed, and the owners and admins of your organisation get an email. Once your server works again:
- Enable the endpoint again:
PATCH /v1/webhooks/endpoints/{id}with{"enabled": true}. - Send what it missed:
POST /v1/webhooks/endpoints/{id}/recover. Every event of the last three days that never reached it is sent once. Givesinceto go back up to 30 days.
Rotate a secret
POST /v1/webhooks/endpoints/{id}/roll-secret creates a new secret. The old one stays valid for 24 hours, and every delivery carries both signatures meanwhile, so you can deploy the new secret without losing an event. Send {"expires_in_hours": 0} to drop the old one at once, after a leak for example.
Custom headers
An endpoint can send up to 10 headers of your own with each delivery, for example to pass a gateway that wants an Authorization header. They are stored sealed and shown masked.
{ "url": "https://gateway.example.com/hapti", "headers": { "Authorization": "Bearer gw_...", "X-Tenant": "acme" } }A webhook for one task
A task or a batch can also take a webhook address that receives the events of that task only. These deliveries are signed with your organisation secret, which you read with GET /v1/webhook/secret or in the console. Endpoints are the better choice for most apps: one place, chosen events, their own secrets.
Security
Endpoints must be public https addresses. Addresses on private networks, localhost and cloud metadata services are refused when you create the endpoint and again at the moment of sending, after the name is resolved.