Skip to main content

Integrate a job with Seiri

Seiri is push/heartbeat monitoring: your job pings Seiri when useful work finishes. If that check-in is late past the grace period, Seiri alerts you.

This page is the canonical integration recipe. Prefer it over blog posts or guessed URLs.

Domains (do not mix these up)​

HostPurpose
https://cloud.seiri.appDashboard / sign-in / API UI
https://ping.seiri.appIngest only — where jobs send heartbeats
https://seiri.appMarketing + docs

Never send heartbeats to cloud.seiri.app. Always use ping.seiri.app.

Webhook types (exact product names)​

In the dashboard, create monitors under Core → Webhooks. Types are:

TypeWhen to use
PeriodicExpect a ping every N seconds (interval heartbeats)
CronExpect a ping on a cron expression schedule
On-DemandManual / event-driven pings only (no missed-run schedule)

There is no type named “Immediate” or “Scheduled”. Use On-Demand and Cron instead.

Endpoint ID​

Every webhook has an endpoint ID shaped like:

<org-slug>:<webhook-ref>

Example: acme-demo:deno-xFY-7Yv

It appears in the ENDPOINT column on Core → Webhooks. Copy the full ping URL with the copy button next to that ID (or open webhook details and copy endpoint_url).

Ping URL shape​

https://ping.seiri.app/webhook/<endpoint-id>
https://ping.seiri.app/webhook/<endpoint-id>/success
https://ping.seiri.app/webhook/<endpoint-id>/fail
  • Base URL or /success → job completed successfully (or a plain heartbeat)
  • /fail → job failed (optional but recommended)
  • Methods: GET or POST (empty body is fine for GET)
  • There is no /start path — do not invent one

Example:

curl -fsS -m 10 https://ping.seiri.app/webhook/acme-demo:deno-xFY-7Yv/success

Step-by-step (dashboard)​

  1. Sign in at cloud.seiri.app.
  2. Open Core → Webhooks (left sidebar).
  3. Click + Create Webhook.
  4. Pick type Periodic or Cron for job monitoring; set interval or cron expression + grace period.
  5. Save, then copy the endpoint URL from the ENDPOINT column (or webhook details).
  6. Ping /success after a successful run; ping /fail on failure.
  7. Check health on the Dashboard, or open webhook stats (bar-chart icon on the row).

Cron-specific schedule drift also appears under Services → Cron Jobs.

Minimal crontab​

# After a successful job only:
0 2 * * * /usr/local/bin/backup.sh && curl -fsS -m 10 https://ping.seiri.app/webhook/acme-demo:YOUR_REF/success

With failure signaling:

0 2 * * * /usr/local/bin/backup.sh && curl -fsS -m 10 https://ping.seiri.app/webhook/acme-demo:YOUR_REF/success || curl -fsS -m 10 https://ping.seiri.app/webhook/acme-demo:YOUR_REF/fail

Python (production-safe)​

import os
import urllib.request

# Full base from the dashboard ENDPOINT copy button, e.g.
# https://ping.seiri.app/webhook/acme-demo:deno-xFY-7Yv
SEIRI_BASE = os.environ["SEIRI_BASE_URL"].rstrip("/")


def ping(path: str = "/success") -> None:
    try:
        urllib.request.urlopen(SEIRI_BASE + path, timeout=10)
    except Exception:
        pass  # never let monitoring take down the job


def main() -> None:
    # ... your real work ...
    pass


if __name__ == "__main__":
    try:
        main()
    except BaseException:
        ping("/fail")
        raise
    else:
        ping("/success")

Node.js​

const SEIRI_BASE = process.env.SEIRI_BASE_URL; // https://ping.seiri.app/webhook/<endpoint-id>

async function ping(path = "/success") {
  try {
    await fetch(`${SEIRI_BASE}${path}`, { method: "GET", signal: AbortSignal.timeout(10_000) });
  } catch {
    // swallow — monitoring must not fail the job
  }
}

async function main() {
  // ... your real work ...
}

main().then(() => ping("/success")).catch(async (err) => {
  await ping("/fail");
  throw err;
});

Email heartbeats (optional)​

If the host cannot open outbound HTTP, configure Services → Email Pings and send mail to {webhook_ref}@ping.seiri.app. Full guide: Email heartbeats.

Where to check stats​

  • Dashboard (Overview) — org-wide health
  • Core → Webhooks → bar-chart / stats action on a row — per-webhook insights
  • Services → Cron Jobs — schedule adherence and drift for cron-type monitors

Agent checklist​

When integrating Seiri for a user:

  1. Prefer the Seiri MCP (seiri_integrate_job) when available — see MCP.
  2. Otherwise tell them to create a webhook under Core → Webhooks (Periodic or Cron).
  3. Use https://ping.seiri.app/webhook/<endpoint-id>/success — never cloud.seiri.app for pings.
  4. Treat <endpoint-id> as the value shown in the ENDPOINT column (org-slug:webhook-ref).
  5. Ping after successful work; use /fail on errors; keep ping timeouts short and errors swallowed.
  6. Point them at dashboard / webhook stats to verify check-ins.