AthausDocs

REST API: webhooks

Events to an address of your system: set one up, verify the signature, understand retries, rotate the secret.

Last updated:

A webhook endpoint is an address of your system to which Athaus sends an event as soon as it happens: a new inquiry, a booked viewing. You stop polling. What an endpoint missed, you fetch through events.

Set one up

curl https://api.athaus.ai/v1/webhookEndpoints \
  -H "Authorization: Bearer ath_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.org/hooks/athaus",
    "events": ["inquiry.received", "viewing.booked"],
    "description": "CRM sync"
  }'

The answer is 201 and carries the secret Athaus signs with:

{
  "object": "webhook_endpoint",
  "id": "0190f3b0-5a71-7c3e-8f12-6d0a9e4b7c21",
  "url": "https://example.org/hooks/athaus",
  "description": "CRM sync",
  "events": ["inquiry.received", "viewing.booked"],
  "status": "enabled",
  "disabledReason": null,
  "disabledAt": null,
  "apiVersion": "v1",
  "apiKeyId": "0190f3a4-1d2e-7a55-8c10-3b9e4f6a2d08",
  "secretRotationEndsAt": null,
  "lastDelivery": null,
  "createdAt": "2026-11-12T08:00:00Z",
  "updatedAt": "2026-11-12T08:00:00Z",
  "secret": "whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSwMfKQ9r8GKYo="
}

The secret appears in this answer and in the answer to a rotation, nowhere else. Store it at once. Later reads do not show it.

The address must be https, point to a public address and must not contain a user name. Athaus checks this when you create the endpoint and again before every delivery, because a name can point elsewhere by then. Machines in your own network, localhost and the metadata address of a cloud provider are not a target. An office has at most 20 endpoints (webhook_endpoint_limit_exceeded).

POST /v1/webhookEndpoints and the rotation of the secret take no Idempotency-Key: the answer carries a secret that is never stored. If an answer got lost, delete the endpoint and create it again.

Scopes

The key needs the scope propose, the level write on webhookEndpoints, and the level read on the resource of every event you subscribe to (Scopes and levels). A request for more is 403 (insufficient_permissions); events are never dropped silently. The check applies to every change of the endpoint.

Only a key created by the management of the office gets webhookEndpoints, like contacts.

The endpoint belongs to the key that created it. If that key is revoked, or ends when its issuer leaves, the endpoint stops delivering; GET shows disabledReason: key_revoked. The key list is the one place where you end access.

Events

TypeWhenResourceLevel
inquiry.receivedan inquiry arrivedinquiriesread
message.receiveda message on an inquiry arrivedinquiriesread
viewing.bookeda viewing was bookedviewingsread
viewing.canceleda guest canceledviewingsread
viewing.upcominga viewing is about to startviewingsread
file.processeda document on a listing was readfilesread
project.createda project was createdprojectsread
project.updateda project was changed or removedprojectsread
proposal.pendinga proposal from What leaves the office waits for a yesinquiriesread

These are the same names as in MCP Events. Only the endpoint of the key that created the proposal receives proposal.pending, just as GET /v1/proposals shows only that key's proposals; data.object is the proposal. There is no event for changes to listings and contacts; follow them with updatedSince (Pagination). New types arrive without a new version: ignore what you do not know.

What arrives

A POST with JSON to your address. The body is an event:

{
  "object": "event",
  "id": "0190f3c1-22aa-7d10-9b3e-0f8e5c6a1d44",
  "type": "inquiry.received",
  "createdAt": "2026-11-12T08:14:03.512Z",
  "apiVersion": "v1",
  "livemode": true,
  "data": {
    "object": {
      "object": "inquiry",
      "id": "0190f3c1-2217-7a02-8c4b-5e1d7a9b3f10",
      "listingId": "0190f3a2-7c1e-7b0e-9a41-5d2f6e8c3b17",
      "status": "new",
      "source": "athaus",
      "answered": false,
      "replyable": true,
      "name": "Mia K.",
      "email": null,
      "phone": null,
      "contactId": null,
      "contactConsent": "not_requested",
      "seeker": null,
      "createdAt": "2026-11-12T08:14:03Z",
      "updatedAt": "2026-11-12T08:14:03Z"
    }
  }
}

data.object is the inquiry as GET /v1/inquiries/{id} returns it. It is in the state of the moment Athaus delivers. If it no longer exists, you get { "object": "inquiry", "id": "...", "deleted": true } instead.

livemode is false for an endpoint you create with a test key: it belongs to the test office, receives its events and is signed the same way. Webhooks are the only thing that leaves the test office.

Three headers come with it, as Standard Webhooks describes them:

HeaderContent
webhook-idthe id of the event, the same on every retry
webhook-timestampUnix seconds of this attempt, new on every attempt
webhook-signaturev1, and the signature in base64; two during a rotation, separated by a space

Verify the signature

Verify every delivery before you trust it. The signature is HMAC-SHA256 over {webhook-id}.{webhook-timestamp}.{body} with the secret (without whsec_, base64-decoded). Compute it over the bytes that arrived, not over re-serialised JSON.

import { createHmac, timingSafeEqual } from "node:crypto";
import express from "express";

function genuine(body, headers, secret) {
  const id = headers["webhook-id"];
  const timestamp = headers["webhook-timestamp"];
  const signatures = headers["webhook-signature"];
  if (!id || !timestamp || !signatures) return false;
  // A delivery older than five minutes is not accepted.
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false;
  const key = Buffer.from(secret.replace(/^whsec_/, ""), "base64");
  const expected = createHmac("sha256", key).update(`${id}.${timestamp}.${body}`).digest();
  return signatures.split(" ").some((s) => {
    const [version, value] = s.split(",");
    if (version !== "v1" || !value) return false;
    const given = Buffer.from(value, "base64");
    return given.length === expected.length && timingSafeEqual(given, expected);
  });
}

const app = express();
app.post("/hooks/athaus", express.raw({ type: "application/json" }), (req, res) => {
  if (!genuine(req.body.toString("utf8"), req.headers, process.env.ATHAUS_WEBHOOK_SECRET)) return res.sendStatus(400);
  const event = JSON.parse(req.body.toString("utf8"));
  // The same webhook-id can arrive more than once: process each event once.
  res.sendStatus(200);
});

Answer fast and work afterwards. Ready-made Standard Webhooks libraries verify the same thing.

Answers and retries

Answer with any 2xx within 10 seconds. Athaus does not read the body of your answer and does not follow a redirect. Any other answer, a timeout or a connection error counts as not delivered and is retried. Delivery is at least once, so you recognise a retry by webhook-id.

AttemptWhen
1at once
21 minute after the first
35 minutes after the second
430 minutes after the third
52 hours after the fourth
66 hours after the fifth
712 hours after the sixth
824 hours after the seventh
924 hours after the eighth

Each gap can be up to a tenth longer. Together that is about three days. If the ninth attempt fails too, Athaus drops that one event; it stays retrievable through GET /v1/events. A 413 does the same at once, a 410 from the receiver disables the endpoint at once. What happens when nothing ever gets through is under When your endpoint fails.

GET /v1/webhookEndpoints/{id} shows whether an endpoint delivers:

MemberMeaning
statusenabled or disabled
disabledReasondisabled_by_user, target_not_allowed, endpoint_gone, delivery_failing or key_revoked
disabledAtsince when it is disabled, by you or by Athaus; null while it delivers
lastDeliverytime (at), HTTP status and kind of error of the last attempt; failingSince says since when everything fails

When your endpoint fails

Athaus keeps a clock for every endpoint: the first failed attempt since the last successful delivery (lastDelivery.failingSince).

  • A single 2xx resets the clock, even if other events are still being retried.
  • After one day without a success, Athaus emails the management of the office (owner and admin): the endpoint is failing, and when it will be disabled. The email comes once per outage.
  • After five days without a success, Athaus disables the endpoint. status is disabled, disabledReason is delivery_failing, disabledAt gives the time. A second email says so, with the address (without the path), the last error and the way back. Deliveries that are still waiting are not attempted any more.
  • If nothing was due in those five days, the endpoint stays on. The clock only runs while deliveries fail.

The email goes to the management and not to whoever issued the key, so it reaches someone even if the issuer has left the office.

Disabled does not mean lost. You catch up on the events of the last 30 days through GET /v1/events. Turn the endpoint on again with PATCH and { "disabled": false } once your receiver runs; the address is checked again and the clock starts over.

Rotate the secret

curl -X POST https://api.athaus.ai/v1/webhookEndpoints/0190f3b0-5a71-7c3e-8f12-6d0a9e4b7c21/rotateSecret \
  -H "Authorization: Bearer ath_live_..."

The answer carries the new secret, once. The previous one keeps signing for 24 hours (secretRotationEndsAt names the end): during that time every delivery has two signatures, and a receiver that knows either secret accepts it. This is how you swap the secret on your side without a delivery failing. If you rotate again within the 24 hours, the one that was current becomes the previous one.

Test, change, delete

  • POST /v1/webhookEndpoints/{id}/test sends one event of type webhook_endpoint.test, exactly once, and answers with the result (delivered, status, error). It retries nothing and leaves the state of the endpoint as it is.
  • PATCH changes url, events, description and disabled as a merge patch.
  • DELETE removes the endpoint.
  • GET /v1/webhookEndpoints lists the endpoints of the office, newest first.

Every operation is in the reference.

Keep reading

On this page