Webhooks

Instead of polling, you can have BananaHub POST to a URL of yours when a job reaches a terminal state (done or failed). Every delivery is signed so you can confirm it came from us.

Configure a webhook

Register one or more webhooks in the web panel. Each registered webhook has its own URL and its own webhook secret (shown next to the URL). The secret signs every delivery sent to that URL — copy it into the matching receiver to verify signatures. Treat it like a password. A delivery is always signed with the secret of the registered webhook whose URL it is sent to. That is the secret you verify against — no global or shared secret is involved.

Choosing which webhook receives a job

You have two options:

Default (account webhook)
Per request (callback_url)

If you register a single webhook and send no callback_url, every terminal job is delivered to it automatically. (When multiple webhooks are registered and no callback_url is given, the oldest one is used as the default.)

Pass a callback_url in the generation request body to route that job’s webhook to a specific URL. This is how you target different environments (production, staging, …) from the same account — point each request at the corresponding registered webhook URL.

{
  "prompt": "...",
  "callback_url": "https://staging.example.com/webhooks/bananahub"
}

The callback_url must exactly match a URL you registered in the panel. Only then is the delivery signed with that webhook’s secret and verifiable. A callback_url pointing at an unregistered URL cannot be validated and should not be used.

Delivery

When a job finishes, we send a single POST with a JSON body and these headers:

Header	Description
`Content-Type`	`application/json`
`X-Signature`	HMAC-SHA256 signature in the form `sha256=<hex>`. See verification.
`X-Timestamp`	Unix timestamp (seconds) of when the request was sent.

A delivery counts as successful when your endpoint responds with any 2xx status. Anything else (or a timeout) is retried — see Retries.

Payload

string

UUID of the job.

string

Terminal status: done or failed.

object | null

Present (non-null) only when status is done.

Show result

string

Presigned download URL for the generated image. Valid for 24 hours.

string | null

Failure reason. Present only when status is failed, otherwise null.

object | null

Echo of the metadata you supplied on the generation request. Keys beginning with an underscore (_) are stripped before sending. null if you supplied none.

The webhook payload is similar to GET /jobs/{job_id} but not identical: it omits the created_at / started_at / finished_at timestamps and adds your metadata. Verify against the fields documented here.

{
  "job_id": "0193a7f2-1c4a-7e0b-9b3a-2f1d8c6e4a55",
  "status": "done",
  "result": {
    "image_url": "https://bananahub.io/results/...?X-Amz-Signature=..."
  },
  "error": null,
  "metadata": { "order_id": "abc123" }
}

{
  "job_id": "0193a7f2-1c4a-7e0b-9b3a-2f1d8c6e4a55",
  "status": "failed",
  "result": null,
  "error": "Provider returned no image",
  "metadata": null
}

Verify the signature

We compute HMAC-SHA256("{X-Timestamp}.{body}", secret) and send it as X-Signature: sha256=<hex>, where body is the JSON payload serialized with sorted keys and no whitespace.

Do not HMAC the raw bytes you received. Re-serialize the parsed JSON with sorted keys and compact separators, exactly as below — otherwise key ordering will not match and verification fails.

Re-serialize the body

Parse the JSON and dump it with sorted keys and no spaces: json.dumps(payload, sort_keys=True, separators=(",", ":")).

Build the signed message

Concatenate the timestamp header and the serialized body: "{X-Timestamp}.{body}".

Compute and compare

Compute HMAC-SHA256(message, your_webhook_secret), hex-encode it, prefix with sha256=, and compare to X-Signature using a constant-time comparison.

Reject stale deliveries

Reject the request if |now - X-Timestamp| > 300 seconds to guard against replays.

import hmac, hashlib, json, time

WEBHOOK_SECRET = "your_secret_here"  # from the web panel

def verify_webhook(raw_body: bytes, x_signature: str, x_timestamp: str) -> bool:
    if abs(time.time() - int(x_timestamp)) > 300:
        return False
    payload = json.loads(raw_body)
    body = json.dumps(payload, separators=(",", ":"), sort_keys=True)
    message = f"{x_timestamp}.{body}"
    expected = "sha256=" + hmac.new(
        WEBHOOK_SECRET.encode(),
        message.encode(),
        hashlib.sha256,
    ).hexdigest()
    return hmac.compare_digest(expected, x_signature)

const crypto = require("crypto");
const WEBHOOK_SECRET = "your_secret_here"; // from the web panel

function verifyWebhook(rawBody, xSignature, xTimestamp) {
  if (Math.abs(Date.now() / 1000 - Number(xTimestamp)) > 300) return false;

  const payload = JSON.parse(rawBody);
  const body = JSON.stringify(
    Object.fromEntries(Object.entries(payload).sort()),
    null,
    0
  );
  const message = `${xTimestamp}.${body}`;
  const expected =
    "sha256=" +
    crypto.createHmac("sha256", WEBHOOK_SECRET).update(message).digest("hex");

  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(xSignature));
}

The Node.js example sorts only top-level keys. If your payload contains nested objects, sort recursively to match our serialization.

Retries

If a delivery does not return 2xx, we retry up to 6 times with increasing delays:

Attempt	Delay after previous
1st retry	1 minute
2nd retry	2 minutes
3rd retry	5 minutes
4th retry	10 minutes
5th retry	15 minutes
6th retry	20 minutes

That is 7 delivery attempts over roughly 53 minutes before the webhook is marked failed. Each attempt is re-signed with a fresh X-Timestamp, so validate every delivery independently and make your handler idempotent on job_id.

Get Started

Core Concepts

Gemini-compatible API

Jobs & Account

API Reference

Configure a webhook

Choosing which webhook receives a job

Delivery

Payload

Verify the signature

Retries

​Configure a webhook

​Choosing which webhook receives a job

​Delivery

​Payload

​Verify the signature

​Retries

Configure a webhook

Choosing which webhook receives a job

Delivery

Payload

Verify the signature

Retries