Webhooks
Moth DocsGuides
Moth can tell your server when a job ends, so your code doesn't have to keep reading it.
Give a key a URL
In Moth Console, open the key, choose Edit and add a webhook URL, or send
webhook_urlto the keys endpoints. It must be https on a public address.Keep its secret
The key's facts show its signing secret, which starts with
whsec_. Your server uses it to check that each event came from Moth.Answer with 2xx
When a job made with that key succeeds or fails, Moth posts the event to the URL. Answer with any 2xx within 10 seconds and do slow work afterwards.
The event
{
"id": "evt_3kQ9wR7tY2uI5oP8aS1dF4gH",
"object": "event",
"type": "job.succeeded",
"created": 1793347214,
"data": {
"job": {
"id": "job_7Hc2pW9kLm4Qx8Rt1Vz3",
"object": "job",
"model": "nano-banana-2",
"modality": "image",
"status": "succeeded",
"created_at": 1793347200,
"completed_at": 1793347214,
"unit": "image",
"units": 1,
"held_usd": "0.047059",
"charged_usd": "0.047059",
"progress": 1,
"outputs": [
{
"index": 0,
"url": "/v1/jobs/job_7Hc2pW9kLm4Qx8Rt1Vz3/output/0",
"content_type": "image/png"
}
]
}
}
}type is job.succeeded or job.failed, and data.job is the same object Read a job returns, with the job's ID, model, status, charge and output links. An event never carries the prompt or a file, so fetch the outputs with your key as usual.
Check the signature
Each event comes with a moth-signature header holding t, the time in seconds, and v1, the HMAC-SHA256 of the time, a dot and the raw body, keyed with the secret. Work it out the same way, compare the two in constant time, and turn away an event more than five minutes old.
import { createHmac, timingSafeEqual } from "node:crypto";
// rawBody is the request body exactly as it arrived, before any JSON parsing.
export function fromMoth(rawBody: string, signature: string, secret: string): boolean {
const parts = Object.fromEntries(signature.split(",").map((p) => p.split("=")));
if (Math.abs(Date.now() / 1000 - Number(parts.t)) > 300) return false;
const expected = createHmac("sha256", secret).update(`${parts.t}.${rawBody}`).digest("hex");
return typeof parts.v1 === "string" && parts.v1.length === expected.length
&& timingSafeEqual(Buffer.from(parts.v1), Buffer.from(expected));
}import hashlib, hmac, time
def from_moth(raw_body: bytes, signature: str, secret: str) -> bool:
parts = dict(p.split("=", 1) for p in signature.split(","))
if abs(time.time() - int(parts["t"])) > 300:
return False
signed = parts["t"].encode() + b"." + raw_body
expected = hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest()
return hmac.compare_digest(expected, parts.get("v1", ""))Retries
An event that gets an answer other than 2xx, a redirect, or no answer within 10 seconds is tried again after 1 minute, 5 minutes, 30 minutes, 2 hours and 6 hours, and then dropped. Each try goes to the key's URL as it is at that moment, so a URL you fix catches up on what is pending, and removing the URL or revoking the key drops it.
The same event can arrive more than once, for instance when your answer was lost, so use the moth-event-id header to do its work only once.
What Moth keeps. An event is kept for 24 hours so it can be retried, and then deleted. Moth posts only to public https addresses and never follows a redirect.