Webhooks — what Tier A gets

Three different ideas appear in this repo. Tier A integrators (direct Gommo public API) only need the first row for media jobs.

Kind	Tier A (public API)	Where documented
Job finished (image/video/…)	No — your app polls	Request lifecycle · FAQ
Payment / top-up (user bought credits)	Not part of default integrator contract; dealer/Gommo billing on api.gommo.net when official	Billing (operators) · Gommo platform roadmap
Outbound job webhooks (gateway → your HTTPS URL)	Not on public Gommo API today — self-host preview	Observability (preview)

Golden rule

If you integrate v2.api.gommo.net without self-hosting this gateway, plan on POST /ai/jobs/{id}?media=… polling — not a job-completion webhook.

Media jobs (Tier A)

Gommo does not push “job done” to your server on the standard public integrator flow. Async lifecycle:

1. POST /ai/jobs/{type}/{model} → job id
2. Poll until result_url / terminal failure — Request lifecycle

Optional Mode B when you deploy this repo: wait: true on POST /gateway/jobs/* blocks until poll finishes, or register gateway observability webhooks (preview). That is not required for Tier A.

Payment webhooks (operators, not default Tier A)

Self-hosted /billing/webhook/payos and similar routes notify your gateway when a checkout provider marks an order paid — then the gateway may call Gommo sendBalances / payment sync. That is credit top-up plumbing, not “your image job finished.”

• Integrators guiding users to buy Gommo credits: follow dealer / Gommo flows — do not assume PayOS URLs from this repo in production Tier A docs.
• See Deploy and Billing reference only when you operate a gateway.

Gateway observability webhooks (preview)

The portal Observability page can register HTTPS endpoints that receive JSON when gateway REST finishes polling a job (job.completed / job.failed). Scope is limited (gateway job routes, beta) — see Observability.

Coming to Gommo platform

Outbound job webhooks and portal observability UX are previews on this site. When Gommo ships platform-wide behavior, use Gommo’s official docs and domains — not a hard dependency on self-host.

→ Gommo platform roadmap

Common mistakes

Mistake	Reality
Wait for Gommo to POST when a video render finishes	Poll (or self-host wait: true / gateway webhook preview)
Point PayOS webhook at v2.api.gommo.net	Wrong host — billing/payment is api.gommo.net / operator gateway
Enable Observability webhooks and skip polling in a mobile app calling public API	Webhooks only fire for gateway job paths you control
Confuse usage-history with webhooks	Usage APIs are pull; webhooks are push (gateway preview only today)

Next

• Request lifecycle
• Common errors
• Integration modes — Mode A vs B/C