Key facts
| Event types | batch.completed, fine_tuning.completed, invoice.paid, key.rotated, quota.warning, quota.exceeded, model.deprecated, usage.threshold, audit.alert |
| Signature | HMAC-SHA256 signed deliveries |
| Configuration | Dashboard → Webhooks |
| Transport | HTTPS endpoint you host |
| Delivery handling | Return a 2xx quickly; process asynchronously |
| Idempotency | Design handlers to tolerate duplicate deliveries |
| SIEM export | Audit events can also flow to Splunk, Sentinel, QRadar and Chronicle |
| Product status | Live |
TL;DR
- Webhooks replace polling for quota, key, model and billing events.
- Verify HMAC-SHA256 signatures on the raw body before parsing.
- Acknowledge fast, then process in a queue — never do work in the request.
- Make handlers idempotent; duplicates happen in every webhook system.
- Use audit.alert and quota events to trigger security and cost runbooks.
How it works, step by step
- Create an HTTPS endpoint with a valid certificate and a dedicated path.
- Register it in the dashboard and store the signing secret in your secret manager.
- Verify the HMAC-SHA256 signature against the raw request body before parsing JSON.
- Return 2xx immediately and enqueue the event for asynchronous processing.
- Deduplicate by event ID and make each handler safe to run twice.
- Route events: quota to finance tooling, key.rotated to security, model.deprecated to owners.
- Monitor delivery failures and treat repeated non-2xx responses as an incident.
Try it yourself
Open the OpenAI-compatible API tester →
The event catalogue
Nine event types cover operations, security and billing:
- Capacity and cost:
quota.warning,quota.exceeded,usage.threshold— trigger budget reviews before a cap blocks production. - Security and lifecycle:
key.rotated,audit.alert— feed access reviews and anomaly response. - Platform changes:
model.deprecated— start migration work while you still have runway. - Long-running jobs:
batch.completed,fine_tuning.completed— resume pipelines without polling. - Billing:
invoice.paid— reconcile finance systems automatically.
Verifying signatures properly
An unsigned webhook endpoint accepts instructions from anyone who knows the URL. Verify every delivery:
- Read the raw request body bytes — do not let a framework re-serialise JSON before verification.
- Compute the HMAC-SHA256 of the raw body with your signing secret.
- Compare against the signature header using a constant-time comparison.
- Reject on mismatch with a non-2xx status and log the attempt.
- Optionally enforce a timestamp tolerance to block replay of old payloads.
Rotate the signing secret like any other credential, and support two active secrets during rotation windows.
Handling delivery semantics
Webhook senders retry failed deliveries, so duplicates and out-of-order arrivals are normal. Return a 2xx as soon as the event is durably queued, then do the real work in a worker. Store processed event IDs to deduplicate, and make handlers idempotent so a replay cannot double-charge, double-provision or double-notify. If your handler calls back into Plugsky, use an Idempotency-Key on those POSTs as well. Keep a dead-letter queue for events that fail processing repeatedly, and alert when it grows — silent webhook failure is indistinguishable from no events at all.
Automation patterns worth building
- Cost guardrails: on quota.warning, notify the owning team and open a ticket; on quota.exceeded, pause non-critical batch jobs automatically.
- Security response: on key.rotated outside a change window, alert security and review audit logs for the key.
- Deprecation pipeline: on model.deprecated, create a migration task with the model name, owner and deadline in the payload.
- Pipeline resumption: on batch.completed, fetch results and continue the workflow without polling the API.
Keep the webhook receiver small: verify, persist, acknowledge. Everything else belongs in your normal job infrastructure. See /docs for the current event payloads and signing header names.
Honest comparison
| Capability | Plugsky webhooks | Polling the API | Email-only alerts |
|---|---|---|---|
| Latency | Near real time on event | Minutes depending on interval | Variable, human-paced |
| Coverage | 9 event types across ops, security, billing | Only what you poll | Whatever ops sends |
| Security | HMAC-SHA256 signed payloads | Authenticated poll | Unverified inbox |
| Automation fit | Event-driven workers | Cron jobs and state diffs | Manual |
| Failure handling | Retries plus your dead-letter queue | Next poll may miss state | None |
| Audit link | audit.alert flows to SIEM too | Custom queries | Not applicable |
Frequently asked questions
What events can I subscribe to?
Nine documented types: batch.completed, fine_tuning.completed, invoice.paid, key.rotated, quota.warning, quota.exceeded, model.deprecated, usage.threshold and audit.alert. Configure them under Dashboard → Webhooks.
How are webhooks secured?
Deliveries are signed with HMAC-SHA256. Verify the signature over the raw request body with your signing secret and a constant-time comparison before trusting any payload.
Should my handler process the event inline?
No. Verify, persist the event, return 2xx quickly, then process it asynchronously in a worker. Slow handlers cause retries and duplicate processing.
How do I handle duplicate deliveries?
Deduplicate by event ID and make handlers idempotent. Every webhook system retries, so a handler that runs twice must produce the same result.
What happens if my endpoint is down?
Deliveries are retried and failures are visible in your monitoring. Keep a dead-letter queue and alert on growth so missed events do not go unnoticed.
Can webhooks trigger security automation?
Yes. key.rotated and audit.alert are natural triggers for security runbooks, and audit events can also export to Splunk, Sentinel, QRadar or Chronicle.
Do webhooks replace the status page?
No. Webhooks report account-level events; platform incidents are published on the status page. Alert on both so you distinguish your problem from ours.
Is there a webhook testing tool?
The docs cover the event catalogue and signing. For API-side checks, use the OpenAI-compatible API tester to reproduce requests before wiring automation.