Send Heartbeats as CloudEvents

YipYap’s ingest endpoint accepts CloudEvents as heartbeats, status updates, or arbitrary status transitions for any monitor with an integration key.

1. Get the monitor’s ingest URL

On any monitor’s detail page, copy the Integration Key. The ingest URL is:

POST https://console.yipyap.run/api/v1/cloudevents/ingest/{integration-key}

Rate-limited at 60 requests per minute per source IP. Idempotent on the CloudEvent id within 24 hours, duplicate deliveries return 200 OK with no side effect.

2. Accepted event types

`ce.type`	Effect
`run.yipyap.ingest.heartbeat.v1`	Records an `UP` check with any `data.note` attached as metadata.
`run.yipyap.ingest.status.v1`	Sets the monitor’s status from `data.status` (`up`, `down`, or `degraded`), with optional `data.message`.

Anything else is rejected with 422 Unprocessable Entity. More inbound types may be added in later phases.

3. Knative SinkBinding example

Emit a heartbeat from any Kubernetes workload by binding it to the YipYap ingest URL:

apiVersion: sources.knative.dev/v1
kind: SinkBinding
metadata:
  name: yipyap-heartbeat
  namespace: my-ns
spec:
  subject:
    apiVersion: apps/v1
    kind: Deployment
    name: my-batch-worker
  sink:
    uri: https://console.yipyap.run/api/v1/cloudevents/ingest/YOUR-INTEGRATION-KEY
  ceOverrides:
    extensions:
      environment: prod

SinkBinding injects K_SINK and K_CE_OVERRIDES env vars into the Deployment’s pods. Your application code reads K_SINK, constructs a CloudEvent with ce.type=run.yipyap.ingest.heartbeat.v1, and POSTs it.

4. Knative PingSource example

For a scheduled heartbeat from cron-like triggers:

apiVersion: sources.knative.dev/v1
kind: PingSource
metadata:
  name: yipyap-heartbeat-cron
  namespace: my-ns
spec:
  schedule: "*/5 * * * *"
  contentType: application/json
  data: '{"note": "5-minute cron tick"}'
  sink:
    uri: https://console.yipyap.run/api/v1/cloudevents/ingest/YOUR-INTEGRATION-KEY

Note: PingSource produces ce.type=dev.knative.sources.ping by default, which YipYap rejects as unsupported. Use a ContainerSource, a proxy that rewrites the type to run.yipyap.ingest.heartbeat.v1, or the yipyap-knative-source image, which handles this automatically.

5. Plain-curl smoke test (binary mode)

curl -X POST "https://console.yipyap.run/api/v1/cloudevents/ingest/YOUR-KEY" \
  -H "ce-specversion: 1.0" \
  -H "ce-type: run.yipyap.ingest.heartbeat.v1" \
  -H "ce-source: https://my.batch.example.com/worker-42" \
  -H "ce-id: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"note": "batch completed"}'

Expect 200 OK on success.

6. Explicit status change (binary mode)

Mark a monitor DOWN from an external probe:

curl -X POST "https://console.yipyap.run/api/v1/cloudevents/ingest/YOUR-KEY" \
  -H "ce-specversion: 1.0" \
  -H "ce-type: run.yipyap.ingest.status.v1" \
  -H "ce-source: https://probe.example.com/check-service-x" \
  -H "ce-id: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"status": "down", "message": "external probe failed"}'