hermosodocs

Alert events reference

Every event an alert channel can receive, with its payload. Nothing outside this list is ever sent.

Every delivery

A webhook body is {"event": "<name>", ...the fields below, "at": "<ISO time>"}. at is when the event happened, and it is the same on every retry and every resend, so the body bytes are the same too. Headers: webhook-id (the delivery id, the same across retries and resends: use it to drop a duplicate), webhook-timestamp, webhook-signature (see Verify the signature) and hermoso-attempt (the attempt number; informational, not signed).

Slack and Discord get the same events as a readable message.

How Hermoso learns of an event

Events found by checking start counting when the channel is connected: what was already there is not sent.

Choose events

set_alert_events takes group names, exact event names or a family such as post.*. A channel you never configured receives every group marked on by default.

Renders finished or failed (renders)

render.finished

A render (image, video, avatar, edit, upscale and the other background renders) finished. Happens inside Hermoso.

FieldTypeMeaning
okbooleantrue
typestringwhat kind of render
labelstringthe render's name
modelstring|nullthe model it used
urlstring|nullthe finished file
errornullalways null here
{
  "event": "render.finished",
  "ok": true,
  "type": "image",
  "label": "Spring ad",
  "model": "Nano Banana",
  "url": "https://assets.hermoso.ai/a.png",
  "error": null,
  "at": "2026-11-15T10:00:00.000Z"
}

render.failed

A render failed. Happens inside Hermoso.

FieldTypeMeaning
okbooleanfalse
typestringwhat kind of render
labelstringthe render's name
modelstring|nullthe model it used
urlnullno file
errorstringwhy it failed
{
  "event": "render.failed",
  "ok": false,
  "type": "video",
  "label": "Launch teaser",
  "model": null,
  "url": null,
  "error": "The video model refused the prompt.",
  "at": "2026-11-15T10:00:00.000Z"
}

Scheduled posts published, partly published or failed, and posts deleted (posts)

post.published

A scheduled post went out on every channel it was queued for. Happens inside Hermoso.

FieldTypeMeaning
okbooleantrue
idstringthe scheduled post
labelstringits name
channelsstring[]the channels it was queued for
postednumberchannels that published
totalnumberchannels it was queued for
resultsobject[]one row per channel: channel, ok, url, id, account, error
errornullalways null here
{
  "event": "post.published",
  "ok": true,
  "type": "scheduled post",
  "id": "job_abc",
  "label": "Tuesday drop",
  "channels": [
    "instagram",
    "x"
  ],
  "posted": 2,
  "total": 2,
  "results": [
    {
      "channel": "instagram",
      "ok": true,
      "url": "https://www.instagram.com/p/xyz/"
    },
    {
      "channel": "x",
      "ok": true,
      "url": "https://x.com/brand/status/1"
    }
  ],
  "error": null,
  "at": "2026-11-15T10:00:00.000Z"
}

post.partial

A scheduled post went out on some of its channels and failed on others. Happens inside Hermoso.

FieldTypeMeaning
okbooleanfalse
idstringthe scheduled post
postednumberchannels that published
totalnumberchannels it was queued for
resultsobject[]one row per channel; the failed ones carry error
errorstring|nullthe job's own error, if any
{
  "event": "post.partial",
  "ok": false,
  "type": "scheduled post",
  "id": "job_abc",
  "posted": 1,
  "total": 2,
  "results": [
    {
      "channel": "instagram",
      "ok": true
    },
    {
      "channel": "linkedin",
      "ok": false,
      "error": "LinkedIn needs reconnecting."
    }
  ],
  "error": null,
  "at": "2026-11-15T10:00:00.000Z"
}

post.failed

A scheduled post published nothing. Happens inside Hermoso.

FieldTypeMeaning
okbooleanfalse
idstringthe scheduled post
postednumber0
totalnumberchannels it was queued for
resultsobject[]one row per channel, each with error
errorstring|nullwhy
{
  "event": "post.failed",
  "ok": false,
  "type": "scheduled post",
  "id": "job_abc",
  "posted": 0,
  "total": 1,
  "results": [
    {
      "channel": "tiktok",
      "ok": false,
      "error": "TikTok refused the video: too short."
    }
  ],
  "error": "TikTok refused the video: too short.",
  "at": "2026-11-15T10:00:00.000Z"
}

post.deleted

A post was deleted through Hermoso, or a post Hermoso published was found to be gone from the platform when its numbers were next read (`detected: "check"`). Happens inside Hermoso. Platforms: x, threads, instagram, facebook, youtube, linkedin, pinterest, google_business, bluesky, telegram, wordpress, whop.

FieldTypeMeaning
brandstringthe brand (workspace) the event belongs to
channelstringthe platform
post_idstringthe platform's id for the post
urlstring|nullwhere it was
detectedstring"ours" (deleted through Hermoso) or "check" (found gone when its numbers were read)
{
  "event": "post.deleted",
  "brand": "default",
  "channel": "x",
  "post_id": "1890000000000000000",
  "url": null,
  "detected": "ours",
  "at": "2026-11-15T10:00:00.000Z"
}

Drafts waiting for your approval (approvals)

approval.awaiting

The autopilot drafted posts that wait for someone to approve them. Happens inside Hermoso.

FieldTypeMeaning
draftednumbernew drafts
waitingnumberdrafts waiting in total
profileIdstringthe brand (workspace) the event belongs to
reviewUrlstringwhere to review them
{
  "event": "approval.awaiting",
  "drafted": 3,
  "waiting": 5,
  "profileId": "default",
  "reviewUrl": "https://app.hermoso.ai/?review=default#automations/review",
  "at": "2026-11-15T10:00:00.000Z"
}

Competitor-watch findings (watch)

watch.finding

The competitor watch found new ads (or long-running winners) on its scheduled run. Found when Hermoso reads it (a scheduled check or a read you make), sent once.

FieldTypeMeaning
newAdsnumbernew ads found
winnersnumberlong-running winners
brandsstring[]whose ads
adsobject[]up to 25: competitor, platform, id, thumbnail
watchUrlstringwhere to see them
{
  "event": "watch.finding",
  "newAds": 2,
  "winners": 0,
  "brands": [
    "Acme"
  ],
  "ads": [
    {
      "competitor": "Acme",
      "platform": "meta",
      "id": "1234567890",
      "thumbnail": "https://…"
    }
  ],
  "watchUrl": "https://app.hermoso.ai/#watching",
  "at": "2026-11-15T10:00:00.000Z"
}

Credits running low (credits)

credits.low

The account's credit balance dropped below the low-balance line after a render (at most once every 72 hours per brand). Happens inside Hermoso.

FieldTypeMeaning
balancenumbercredits left
thresholdnumberthe low-balance line
billingUrlstringwhere to add credits
{
  "event": "credits.low",
  "balance": 40,
  "threshold": 100,
  "billingUrl": "https://app.hermoso.ai/#billing",
  "at": "2026-11-15T10:00:00.000Z"
}

New lead-form leads (leads)

lead.created

A lead form was filled in (Meta, LinkedIn or Snapchat lead forms). Pushed by the platform the moment it happens. Platforms: meta, linkedin, snapchat.

FieldTypeMeaning
channelstringmeta, linkedin or snapchat
formIdstring|nullthe form
leadIdstring|nullthe lead
fieldsobjectthe answers, when the platform sent them
summarystring|nullone line
{
  "event": "lead.created",
  "channel": "linkedin",
  "formId": "123",
  "leadId": "456",
  "fields": {
    "firstName": "Sam"
  },
  "summary": "New lead on form 123.",
  "at": "2026-11-15T10:00:00.000Z"
}

Accounts connected, disconnected, broken, losing permissions or about to expire (connections)

account.connected

An account was connected to the brand (any sign-in connect, including a partner connect link). Happens inside Hermoso.

FieldTypeMeaning
brandstringthe brand (workspace) the event belongs to
providerstringthe connector
accountobjectlabel, handle, id
link_idstring|nullthe partner connect link, if one was used
statestring|nullthe partner's own state value
account_selection_requiredbooleantrue when accounts must be chosen before posting
{
  "event": "account.connected",
  "brand": "default",
  "provider": "linkedin",
  "account": {
    "label": "Acme",
    "handle": null,
    "id": "123"
  },
  "link_id": null,
  "state": null,
  "account_selection_required": false,
  "at": "2026-11-15T10:00:00.000Z"
}

account.disconnected

An account was disconnected from the brand. Happens inside Hermoso.

FieldTypeMeaning
brandstringthe brand (workspace) the event belongs to
providerstringthe connector
accountstring|nullwhich account
{
  "event": "account.disconnected",
  "brand": "default",
  "provider": "tiktok",
  "account": "@acme",
  "at": "2026-11-15T10:00:00.000Z"
}

account.broken

A connected account stopped working and needs reconnecting (the platform refused its sign-in). Found by the hourly connection check; sent once per incident, again only after it has worked in between. Found when Hermoso reads it (a scheduled check or a read you make), sent once.

FieldTypeMeaning
brandstringthe brand (workspace) the event belongs to
providerstringthe connector
accountstring|nullwhich account, when one of several broke
reasonstring|nullthe platform's own words
stepsstringwhat to do
reconnect_urlstringwhere to reconnect
{
  "event": "account.broken",
  "brand": "default",
  "provider": "instagram",
  "account": "@acme",
  "reason": "The user has changed their password.",
  "steps": "Sign in again.",
  "reconnect_url": "https://app.hermoso.ai/#connectors",
  "at": "2026-11-15T10:00:00.000Z"
}

account.expiring

A connection will stop working soon unless it is renewed (its sign-in has a fixed end). Found by the hourly connection check; sent once per incident. Found when Hermoso reads it (a scheduled check or a read you make), sent once.

FieldTypeMeaning
brandstringthe brand (workspace) the event belongs to
providerstringthe connector
statestring"expiring" (renew it) or "ends" (it ends on that date)
daysnumber|nulldays left
notestringwhat happens and what to do
reconnect_urlstringwhere to renew
{
  "event": "account.expiring",
  "brand": "default",
  "provider": "pinterest",
  "state": "expiring",
  "days": 6,
  "note": "Pinterest stops working in 6 days unless you reconnect it.",
  "reconnect_url": "https://app.hermoso.ai/#connectors",
  "at": "2026-11-15T10:00:00.000Z"
}

account.permissions_changed

A connection is missing permissions the brand needs (someone removed them, or a new feature needs them). Found when the connections list is read; sent once until it is fixed. Found when Hermoso reads it (a scheduled check or a read you make), sent once.

FieldTypeMeaning
brandstringthe brand (workspace) the event belongs to
providerstringthe connector
missingstring[]the permissions it lacks
notestringwhat reconnecting gets back
reconnect_urlstringwhere to reconnect
{
  "event": "account.permissions_changed",
  "brand": "default",
  "provider": "meta",
  "missing": [
    "instagram_manage_comments"
  ],
  "note": "Reconnect Meta to reply to Instagram comments.",
  "reconnect_url": "https://app.hermoso.ai/#connectors",
  "at": "2026-11-15T10:00:00.000Z"
}

Automated ad rules that matched (adrules)

adrule.acted

An automated Google Ads rule with a notify action matched on its run (Meta sends its own rules' notices to the Meta user). Happens inside Hermoso. Platforms: google_ads.

FieldTypeMeaning
brandstringthe brand (workspace) the event belongs to
platformstringgoogle_ads
rule_idstring|nullthe rule
rule_namestringits name
customer_idstringthe Google Ads account
matchednumberobjects it matched
{
  "event": "adrule.acted",
  "brand": "default",
  "platform": "google_ads",
  "rule_id": "r_1",
  "rule_name": "Pause high CPA",
  "customer_id": "1234567890",
  "matched": 2,
  "at": "2026-11-15T10:00:00.000Z"
}

New comments and direct messages (inbox, off unless named)

comment.received

Someone commented on or replied to the brand's post. Pushed by Facebook and Instagram; found when read for the other platforms (`detected: "check"`). Pushed by the platform the moment it happens. Platforms: facebook, instagram, threads, youtube, tiktok, linkedin, bluesky.

FieldTypeMeaning
platformstringthe platform
comment_idstringthe comment
textstringwhat they wrote
fromobjectwho wrote it: id and name or username
occurred_atstring|nullwhen the platform says it happened
reply_withstring|nullthe tool that answers it
detectedstring"push" or "check"
{
  "event": "comment.received",
  "platform": "instagram",
  "instagram_account_id": "1784…",
  "media_id": "1790…",
  "comment_id": "1791…",
  "parent_id": null,
  "text": "Is this in stock?",
  "from": {
    "id": "1785…",
    "username": "sam"
  },
  "occurred_at": "2026-11-15T10:00:00.000Z",
  "reply_with": "reply_to_meta_comment",
  "detected": "push",
  "at": "2026-11-15T10:00:00.000Z"
}

message.received

Someone sent the brand a direct message. Some platforms push it the moment it arrives; for the others it is found when the inbox is read (`detected: "check"`). Pushed by the platform the moment it happens. Platforms: messenger, instagram, whatsapp, line, telegram, x, bluesky, intercom. Pushed by messenger, instagram, whatsapp and line.

FieldTypeMeaning
platformstringthe platform
message_idstringthe message (or conversation, where the platform names no message)
textstringwhat they wrote (empty for a photo or sticker)
fromobjectwho wrote it: their id on that platform, and a name when the platform gives one
occurred_atstring|nullwhen
reply_withstring|nullthe tool that answers it
detectedstring"push" or "check"
{
  "event": "message.received",
  "platform": "messenger",
  "page_id": "1000…",
  "message_id": "m_abc",
  "text": "Do you ship to Canada?",
  "from": {
    "id": "2400…"
  },
  "occurred_at": "2026-11-15T10:00:00.000Z",
  "reply_window_hours": 24,
  "reply_with": "reply_to_meta_message",
  "detected": "push",
  "at": "2026-11-15T10:00:00.000Z"
}

Each channel a post went to, published or failed (posts sent right away too) (channel_posts, off unless named)

post.channel.published

A post went out on one channel. Sent for every publish through Hermoso, right away or scheduled. Happens inside Hermoso. Platforms: facebook, instagram, threads, tiktok, youtube, linkedin, linkedin_page, bluesky, google_business, x, x_article, telegram, pinterest, wordpress, discord, slack, whop, shopify_blog, webflow, wix, whatsapp.

FieldTypeMeaning
brandstringthe brand (workspace) the event belongs to
channelstringthe platform
post_idstring|nullthe platform's id for the post
urlstring|nullthe post
viastringhow it was published: route, agent, mcp or scheduled
post_groupstring|nullshared by every channel of one scheduled post
{
  "event": "post.channel.published",
  "brand": "default",
  "channel": "linkedin",
  "post_id": "urn:li:share:7000000000000000000",
  "url": "https://www.linkedin.com/feed/update/urn:li:share:7000000000000000000",
  "via": "scheduled",
  "post_group": "job_abc",
  "at": "2026-11-15T10:00:00.000Z"
}

post.channel.failed

A post did not go out on one channel. `outcome` says whether nothing was posted or the platform's answer was unclear. Happens inside Hermoso. Platforms: facebook, instagram, threads, tiktok, youtube, linkedin, linkedin_page, bluesky, google_business, x, x_article, telegram, pinterest, wordpress, discord, slack, whop, shopify_blog, webflow, wix, whatsapp.

FieldTypeMeaning
brandstringthe brand (workspace) the event belongs to
channelstringthe platform
outcomestring"not_posted" (nothing went out, safe to retry) or "unconfirmed" (it may be live: check before posting again)
errorstringwhat went wrong
viastringroute, agent, mcp or scheduled
post_groupstring|nullshared by every channel of one scheduled post
{
  "event": "post.channel.failed",
  "brand": "default",
  "channel": "pinterest",
  "outcome": "not_posted",
  "error": "Pinterest needs a board for this Pin.",
  "via": "agent",
  "post_group": null,
  "at": "2026-11-15T10:00:00.000Z"
}

Ads rejected, ads with delivery problems and budgets used up (ads)

ad.rejected

An ad was rejected by the platform's review. Found when the ads are read (list_meta_ads, the Google Ads policy check); sent once per ad until it is approved again. Found when Hermoso reads it (a scheduled check or a read you make), sent once. Platforms: meta, google_ads.

FieldTypeMeaning
brandstringthe brand (workspace) the event belongs to
platformstringmeta or google_ads
ad_accountstringthe ad account
ad_idstringthe ad
ad_namestring|nullits name
reasonstring|nullthe platform's own words
{
  "event": "ad.rejected",
  "brand": "default",
  "platform": "meta",
  "ad_account": "1234567890",
  "ad_id": "120200000000000",
  "ad_name": "Spring video",
  "reason": "Your ad uses before-and-after images.",
  "at": "2026-11-15T10:00:00.000Z"
}

ad.delivery_issue

An ad is approved but has a problem that stops or limits its delivery (Meta WITH_ISSUES, Google approved with limits). Found when the ads are read; sent once per ad until it clears. Found when Hermoso reads it (a scheduled check or a read you make), sent once. Platforms: meta, google_ads.

FieldTypeMeaning
brandstringthe brand (workspace) the event belongs to
platformstringmeta or google_ads
ad_accountstringthe ad account
ad_idstringthe ad
ad_namestring|nullits name
reasonstring|nullthe platform's own words
{
  "event": "ad.delivery_issue",
  "brand": "default",
  "platform": "meta",
  "ad_account": "1234567890",
  "ad_id": "120200000000000",
  "ad_name": "Spring video",
  "reason": "Payment method declined.",
  "at": "2026-11-15T10:00:00.000Z"
}

budget.exhausted

An ad account reached its spending limit, so its ads stopped. Found when the ad account is read; sent once until it has room again. Found when Hermoso reads it (a scheduled check or a read you make), sent once. Platforms: meta.

FieldTypeMeaning
brandstringthe brand (workspace) the event belongs to
platformstringmeta
ad_accountstringthe ad account
spend_capstringthe limit, in the account currency's minor units
amount_spentstringspent against it
currencystring|nullthe account currency
{
  "event": "budget.exhausted",
  "brand": "default",
  "platform": "meta",
  "ad_account": "1234567890",
  "spend_cap": "500000",
  "amount_spent": "500000",
  "currency": "USD",
  "at": "2026-11-15T10:00:00.000Z"
}

WhatsApp message templates approved, rejected or paused (whatsapp)

whatsapp.template_status

Meta approved, rejected, paused or disabled one of the brand's WhatsApp message templates. Pushed by the platform the moment it happens. Platforms: whatsapp.

FieldTypeMeaning
brandstringthe brand (workspace) the event belongs to
waba_idstringthe WhatsApp Business account
template_idstring|nullthe template
namestringits name
languagestring|nullits language
statusstringAPPROVED, REJECTED, PAUSED, DISABLED and the other values Meta sends
reasonstring|nullMeta's reason, when it gave one
{
  "event": "whatsapp.template_status",
  "brand": "default",
  "waba_id": "1638398507841926",
  "template_id": "987",
  "name": "order_update",
  "language": "en_US",
  "status": "REJECTED",
  "reason": "INVALID_FORMAT",
  "at": "2026-11-15T10:00:00.000Z"
}

New mentions of the brand (mentions, off unless named)

mention.received

Someone mentioned the brand. Pushed by Facebook Pages (the Page `mention` webhook); found when read on X, Threads and Bluesky. Found when Hermoso reads it (a scheduled check or a read you make), sent once. Platforms: facebook, x, threads, bluesky.

FieldTypeMeaning
platformstringthe platform
item_idstringthe post or comment that mentions the brand
textstringwhat it says
fromobjectwho wrote it
urlstring|nullwhere it is
occurred_atstring|nullwhen
detectedstring"push" or "check"
{
  "event": "mention.received",
  "platform": "x",
  "item_id": "1890…",
  "text": "@acme love the new drop",
  "from": {
    "name": "sam"
  },
  "url": null,
  "occurred_at": "2026-11-15T10:00:00.000Z",
  "detected": "check",
  "at": "2026-11-15T10:00:00.000Z"
}

New reviews (reviews, off unless named)

review.received

Someone left a review. Found when the reviews are read (Google Business Profile). Found when Hermoso reads it (a scheduled check or a read you make), sent once. Platforms: google_business.

FieldTypeMeaning
platformstringgoogle_business
review_idstringthe review
ratingstring|number|nullthe stars
textstringwhat they wrote (may be empty)
fromobjectthe reviewer's display name
occurred_atstring|nullwhen
reply_withstringthe tool that answers it
detectedstring"check"
{
  "event": "review.received",
  "platform": "google_business",
  "review_id": "accounts/1/locations/2/reviews/3",
  "rating": "FIVE",
  "text": "Great service",
  "from": {
    "name": "Sam"
  },
  "occurred_at": "2026-11-15T10:00:00.000Z",
  "reply_with": "reply_to_google_business_review",
  "detected": "check",
  "at": "2026-11-15T10:00:00.000Z"
}

Replies and bounces on email sequences (email, off unless named)

email.replied

Someone replied to an email sequence (found when the connected mailbox is checked, every 15 minutes while a sequence runs). Found when Hermoso reads it (a scheduled check or a read you make), sent once. Platforms: outlook, smtp.

FieldTypeMeaning
brandstringthe brand (workspace) the event belongs to
sequence_idstring|nullthe sequence
lead_idstring|nullthe lead (never their address)
stoppedbooleantrue when the reply stopped the sequence for them
subjectstring|nullthe reply's subject
{
  "event": "email.replied",
  "brand": "default",
  "sequence_id": "seq_1",
  "lead_id": "lead_1",
  "stopped": true,
  "subject": "Re: quick question",
  "at": "2026-11-15T10:00:00.000Z"
}

email.bounced

An email sequence message bounced (found when the connected mailbox is checked). Found when Hermoso reads it (a scheduled check or a read you make), sent once. Platforms: outlook, smtp.

FieldTypeMeaning
brandstringthe brand (workspace) the event belongs to
sequence_idstring|nullthe sequence
lead_idstring|nullthe lead (never their address)
subjectstring|nullthe bounce notice's subject
{
  "event": "email.bounced",
  "brand": "default",
  "sequence_id": "seq_1",
  "lead_id": "lead_1",
  "subject": "Undeliverable: quick question",
  "at": "2026-11-15T10:00:00.000Z"
}

email.paused

A mailbox or an email sequence was paused on its own: too many bounces or refusals, a spam complaint, a blocked or suspended answer, or a refused sign-in (2026-11-17). Found when Hermoso reads it (a scheduled check or a read you make), sent once. Platforms: outlook, smtp.

FieldTypeMeaning
brandstringthe brand (workspace) the event belongs to
pausedstring"mailbox" or "sequence"
reasonstringbounces, failures, complaint, blocked or auth
whystringthe reason in words, the same sentence the app shows
{
  "event": "email.paused",
  "brand": "default",
  "paused": "mailbox",
  "reason": "bounces",
  "why": "The mailbox ann@acme.test was paused because 2 of 60 emails in the last 7 days bounced (3.3%; the limit is 2.5%). Remove addresses that do not work, then resume it.",
  "at": "2026-11-15T10:00:00.000Z"
}

Always sent

test

You pressed Send test alert (send_test_alert). Sent whatever events a channel has chosen. Happens inside Hermoso.

FieldTypeMeaning
okbooleantrue
messagestringa fixed line
{
  "event": "test",
  "ok": true,
  "message": "Test alert from Hermoso.",
  "at": "2026-11-15T10:00:00.000Z"
}

connected

The hello Hermoso sends when the channel is first connected or its URL replaced. Happens inside Hermoso.

FieldTypeMeaning
okbooleantrue
messagestringa fixed line
{
  "event": "connected",
  "ok": true,
  "message": "Hermoso connected — alert events for this workspace will POST here.",
  "at": "2026-11-15T10:00:00.000Z"
}