Async Acknowledgement
Some receivers can't finish their work while Hookbase waits for the response: an import that takes minutes, a payment that needs the bank's answer, an order that waits for a person to approve it. If the receiver answers 200 straight away, Hookbase records the message as delivered, and a failure afterwards is never retried. With async acknowledgement, the endpoint answers 202 Accepted and reports the outcome later by posting it to a URL that came with the request. Until then the message waits as awaiting_ack. A reported failure, or no report by the deadline, is retried like any other failed attempt. Async acknowledgement requires the Pro or Business plan and applies to HTTP endpoints only.
When to use it
- The work takes longer than the endpoint's request timeout (at most 120 seconds).
- The receiver queues each webhook and processes it later, and a failure in processing should be retried and show in the message log, not be lost after a
200. - The receiver has to call another system before it knows whether the event was applied.
If the receiver can finish within the request, leave it off. A plain 2xx is simpler.
Turn it on
In the dashboard, open an HTTP endpoint's Edit dialog (or Create Endpoint), switch on Async acknowledgement and set Acknowledge within (seconds). Through the API, set asyncAckEnabled, and optionally ackTimeoutSeconds:
curl -X PATCH https://api.hookbase.app/api/organizations/$ORG_ID/webhook-endpoints/$ENDPOINT_ID \
-H "Authorization: Bearer $HOOKBASE_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "asyncAckEnabled": true, "ackTimeoutSeconds": 1800 }'| Field | Type | Default | Rules |
|---|---|---|---|
asyncAckEnabled | boolean | false | HTTP endpoints only. Turning it on needs Pro or Business |
ackTimeoutSeconds | integer | 3600 | 60 to 86,400. How long the receiver has to acknowledge each attempt, counted from when the attempt is sent |
Both fields work on create and update, and every endpoint response returns them.
- Setting
asyncAckEnabled: trueon a queue, bus or bucket endpoint or a polling endpoint returns400with"message": "asyncAckEnabled applies to HTTP endpoints only". Changing an HTTP endpoint to a queue, bus or bucket type turns it off. - It works together with FIFO ordering. See FIFO endpoints.
- A new
ackTimeoutSecondsapplies to attempts sent after the change. An attempt already sent keeps the deadline in its URL. - Turning it off applies to later attempts. Messages already waiting can still be acknowledged, or time out.
- The customer portal and the portal API don't show this setting and can't change it.
Headers your endpoint receives
Every delivery attempt to an endpoint with async acknowledgement on carries two extra headers:
| Header | Value |
|---|---|
x-hookbase-ack-url | https://api.hookbase.app/v1/acks/<token>, where to send the acknowledgement. The token is 75 characters of base64url, signed by Hookbase, and names the message, the attempt number, the deadline and the data region. It is the only credential, so treat the whole URL as a secret |
x-hookbase-ack-deadline | The deadline in Unix seconds, as a decimal string, for example 1763740800 |
Each attempt gets its own URL and deadline. The headers are not sent:
- when the endpoint doesn't have async acknowledgement on, or isn't an HTTP endpoint;
- on test sends, from the dashboard or the portal;
- when less than 60 seconds would be left before the deadline (see Deadlines and timeouts), which can happen near the end of a message's retention period;
- when the endpoint's URL is a Hookbase address (
hookbase.app) such as a source's ingest URL, which answers202itself. Request bins are the exception and get the headers.
Without the headers, a 202 is an ordinary response: a success, unless the endpoint's successStatusCodes leave it out.
A custom header you configured on the endpoint with either name is dropped. The values Hookbase sets always win. Recorded attempts in the dashboard and the attempts API show x-hookbase-ack-url as [redacted]. The portal doesn't return request headers.
Answer 202
To say "the work has started, the outcome follows", answer exactly 202. Only a 202 to an attempt that carried the headers waits for an acknowledgement, even when the endpoint's successStatusCodes leave 202 out.
| Response | What happens |
|---|---|
202, to an attempt with the ack headers | The message waits as awaiting_ack until you acknowledge it or the deadline passes |
Any other 2xx or custom success code, or a 202 to an attempt without the headers | Treated as on any endpoint: delivered when it is a success code for the endpoint, otherwise a failed attempt |
| Anything else | A failed attempt, retried on the endpoint's retry schedule |
The 202 itself is subject to the endpoint's request timeout, so answer it before you start the work.
While the message waits:
- its status is
awaiting_ack, and itsackDeadlinefield holds the deadline as an ISO 8601 time.ackDeadlineisnullin every other status; - its
lastResponseStatusis202, and the attempt's status isaccepted; ?status=awaiting_acklists the waiting messages, in the dashboard API and the portal API.
Send the acknowledgement
POST {x-hookbase-ack-url}
Content-Type: application/jsoncurl -X POST "$ACK_URL" \
-H "Content-Type: application/json" \
-d '{ "status": "success", "message": "Order synced", "result": { "erpId": "SO-1042" } }'There is no API key: the token in the URL is the credential. The body is read as JSON whatever the Content-Type.
| Field | Required | Rules |
|---|---|---|
status | Yes | "success" or "failure", in lowercase |
message | No | A string of up to 1,000 characters. Stored on the attempt as ackMessage. On a failure it is also the attempt's error message |
result | No | Any JSON value, up to 16,384 bytes when serialized and nested at most 64 levels deep. Stored on the attempt as ackResult |
No other fields are allowed, and no string or key may contain a NUL character. The whole body may be up to 65,536 bytes.
{
"data": {
"messageId": "6f1c2a9e-5b8e-4d7a-9a51-1d0f3c2b7e44",
"attempt": 1,
"recorded": true,
"status": "success",
"nextAttemptAt": null
}
}| Field | Meaning |
|---|---|
messageId | The message, which is also the webhook-id header |
attempt | The attempt number this URL belongs to |
recorded | true when this call recorded the outcome. false when the same outcome was already recorded, so sending an acknowledgement again is safe |
status | The message's status: success, awaiting_retry or dlq after a recorded acknowledgement, or its current status when recorded is false |
nextAttemptAt | When a recorded failure will be retried. Otherwise null |
Errors have the body { "error": "<sentence>", "code": "<code>" }:
| Status | Code | When |
|---|---|---|
400 | invalid_ack | The body doesn't follow the rules above. error says what is wrong |
404 | ack_not_found | The token is wrong or altered, or the message no longer exists |
409 | ack_conflict | The attempt was already settled with the other outcome, or the message has moved on |
409 | ack_not_ready | Hookbase is still recording the 202. Send it again after Retry-After (2 seconds) |
410 | ack_expired | More than 60 seconds past the deadline. The attempt timed out and was retried or dead-lettered |
413 | payload_too_large | The body is over 65,536 bytes |
429 | rate_limited | More than 10 acknowledgements in a minute for this attempt. Wait Retry-After (60 seconds) |
503 | data_region_unavailable | The message's data region can't be reached right now. Try again later |
Send it again after ack_not_ready, 429, 503 or a network error. The other errors won't change on a second try. After 410, a new attempt with a new URL follows, unless the message has gone to the DLQ.
Deadlines and timeouts
- The deadline is the time the attempt is sent plus
ackTimeoutSeconds, capped at one hour before the message's retention period ends. If less than 60 seconds would be left, the attempt goes out without the headers. - An acknowledgement is accepted until 60 seconds after the deadline. Later ones get
410 ack_expired. - A sweep that runs every minute times out the attempts nobody acknowledged. An attempt therefore times out between 60 and about 120 seconds after its deadline.
Retries and the dead letter queue
| Outcome | Attempt | Message |
|---|---|---|
success acknowledgement | success, with ackedAt, ackMessage and ackResult | success |
failure acknowledgement | failed, errorType ack_failed, error message Receiver reported failure: <message>, with ackedAt, ackMessage and ackResult | Retried or dead-lettered |
| No acknowledgement in time | timeout, errorType ack_timeout, error message No acknowledgement before the deadline | Retried or dead-lettered |
- A failed or timed-out message waits as
awaiting_retryand is sent again on the endpoint's retry schedule, using the attempts it has left. Once they are spent, or when the next retry would fall after the message's retention ends, it moves to the DLQ withdlqReasonmax_retries_exceeded. Themessage.exhaustedoperational webhook fires withlastErrorTypeack_failedorack_timeout. - A retry is the same message: the same
webhook-id, with a newwebhook-timestamp, signature, ack URL and deadline. After a timeout your receiver may still be working on the earlier attempt when the retry arrives, so deduplicate onwebhook-id. - The
202counts as a successful delivery for the endpoint's health counters and circuit breaker. Failure acknowledgements and timeouts don't count towards the circuit breaker or automatic disabling. - A message in
awaiting_ackcan't be replayed. Wait until it succeeds or fails.
FIFO endpoints
On a FIFO endpoint, a head that answers 202 holds the queue. Nothing behind it is sent until it is acknowledged or times out. A success acknowledgement moves the queue on to the next message. A failure acknowledgement or a timeout leaves the head in place, to be retried before anything behind it.
While the head waits, GET .../webhook-endpoints/{id}/fifo-state reports state: "blocked" with blockedReason: "awaiting_ack", and the head has status: "awaiting_ack" and an ackDeadline.
Plan for the worst case. One attempt can hold the queue for up to ackTimeoutSeconds, plus the 60-second grace period, plus up to 60 seconds until the sweep runs. FIFO endpoints get 5 attempts, so one message can hold the queue for up to five times that, plus the retry delays between attempts. With the default 1-hour timeout, that is over 5 hours. On a FIFO endpoint, set ackTimeoutSeconds close to how long the work really takes.
Usage and billing
In the usage export:
- the attempt answered with
202is a delivery attempt on the UTC day it was made; - it becomes a successful delivery, and its body counts in bytes delivered, on the UTC day the
successacknowledgement arrived (ackedAt); - an attempt that fails by acknowledgement or times out is not a successful delivery. A message that ends in the DLQ counts as failed on the day it was dead-lettered, as on any endpoint.
Security
Warning
Verify the request before you use its ack URL
Anyone who can reach your endpoint can put any URL in a request's headers. Verify the webhook signature first. The signature covers the message ID, timestamp and body, not the headers, so also check that the ack URL's origin is exactly https://api.hookbase.app before you post to it.
Treat the URL as a secret. Anyone who has it can report the outcome of that attempt. Don't log it, and don't pass it to systems that don't need it.
Plan availability
| Plan | Async acknowledgement |
|---|---|
| Free | No |
| Pay As You Go | No |
| Starter | No |
| Pro | Yes |
| Business | Yes |
Turning it on for an endpoint on another plan returns 403 with "error": "Async acknowledgement is only available on Pro and Business plans. ...". Turning it off is always allowed, and ackTimeoutSeconds can be changed on any plan. If you downgrade, endpoints that have it keep it, so a receiver that answers 202 isn't suddenly treated as done before its work is. You can turn it off at any time, but turning it back on needs Pro or Business.
Node.js receiver
import http from 'node:http';
import { Webhook } from 'standardwebhooks';
const wh = new Webhook(process.env.HOOKBASE_SIGNING_SECRET.replace(/^whsec_/, ''));
const ACK_ORIGIN = 'https://api.hookbase.app';
const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
http.createServer(async (req, res) => {
const chunks = [];
for await (const chunk of req) chunks.push(chunk);
const body = Buffer.concat(chunks).toString('utf8');
let payload;
try {
payload = wh.verify(body, req.headers); // throws if the signature doesn't match
} catch {
return res.writeHead(401).end();
}
const webhookId = req.headers['webhook-id'];
const ackUrl = req.headers['x-hookbase-ack-url'];
if (!ackUrl) {
// No ack headers (a test send, or too close to the message's expiry): a 202 would be final,
// so do the work now and answer with the real outcome.
try {
await handle(webhookId, payload);
return res.writeHead(200).end();
} catch {
return res.writeHead(500).end();
}
}
// The signature doesn't cover headers: only ever post to Hookbase.
if (new URL(ackUrl).origin !== ACK_ORIGIN) return res.writeHead(400).end();
res.writeHead(202).end();
// In production, hand the work to a durable job queue along with ackUrl.
let outcome;
try {
const result = await handle(webhookId, payload);
outcome = { status: 'success', message: 'Processed', result };
} catch (err) {
outcome = { status: 'failure', message: String(err?.message ?? err).slice(0, 1000) };
}
await sendAck(ackUrl, outcome);
}).listen(3000);
async function sendAck(ackUrl, outcome) {
for (let attempt = 1; attempt <= 5; attempt++) {
let res;
try {
res = await fetch(ackUrl, {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify(outcome),
});
} catch {
await sleep(attempt * 2000); // network error: sending it again is safe
continue;
}
if (res.ok) return;
const { code } = await res.json().catch(() => ({}));
if (code === 'ack_not_ready' || res.status === 429 || res.status === 503) {
await sleep(Number(res.headers.get('retry-after') ?? 5) * 1000);
continue;
}
// ack_expired: the attempt timed out, and the message is sent again with a new URL.
// ack_conflict, ack_not_found, invalid_ack: sending it again won't help.
console.warn('acknowledgement not recorded', res.status, code); // never log ackUrl
return;
}
}
async function handle(webhookId, payload) {
// The long-running work. Must be idempotent on webhookId: a retry has the same webhook-id.
return { processed: true };
}API
asyncAckEnabled and ackTimeoutSeconds are fields on Create Endpoint and Update Endpoint. Messages carry ackDeadline, and message attempts carry ackedAt, ackMessage and ackResult. The message statistics count waiting messages in awaitingAck, and delivery analytics in summary.awaitingAckCount. The acknowledgement request is listed under Acknowledge a Message.