Key facts
| Transport | HTTPS endpoint you host |
| Signature | HMAC-SHA256 signed deliveries |
| Event types | quota.warning, quota.exceeded, key.rotated, model.deprecated, usage.threshold, invoice.paid, audit.alert, batch.completed, fine_tuning.completed |
| Configuration | Dashboard → Webhooks |
| Response handling | Return 2xx quickly; process asynchronously |
| Delivery semantics | At-least-once; design idempotent handlers |
| SIEM export | Audit events can flow to Splunk, Sentinel, QRadar and Chronicle |
| Status note | Deliveries are live; events tied to coming-soon endpoints depend on the roadmap |
TL;DR
- Signed HTTPS deliveries replace polling for platform events.
- HMAC-SHA256 verification happens before any payload is parsed.
- Nine event types cover quotas, keys, models, usage, invoicing and audit.
- Send audit.alert and key.rotated events into the agency logging platform, keep an append-only record, and treat model.deprecated as a migration trigger for citizen-facing services.
- Handlers must be idempotent because delivery is at-least-once.
How it works, step by step
- List the platform events your public-sector workflows should react to.
- Stand up an HTTPS endpoint you control and register it in Dashboard → Webhooks.
- Verify the HMAC-SHA256 signature over the raw body before parsing.
- Return 2xx quickly and enqueue the event for asynchronous processing.
- Make handlers idempotent so retries and duplicates are safe.
- Add a dead-letter queue and alert when deliveries fail repeatedly.
- Replay test events against a staging endpoint before production cut-over.
Try it yourself
Open the AI data residency checklist →
Why government teams should react to events
Government teams process citizen records, case files and procurement documents under sovereignty rules. Procurement asks for controlled processing, auditability and a clear answer on where data — and model weights — actually live.
Auditability is the requirement: agencies need evidence of key rotation, quota events and model changes in a form their oversight processes can consume.
How Plugsky webhooks work
Register an HTTPS endpoint in Dashboard → Webhooks. Plugsky delivers signed events to the endpoint you host; every delivery is HMAC-SHA256 signed, so verify the signature over the raw body before parsing. Nine event types are documented: quota.warning, quota.exceeded, key.rotated, model.deprecated, usage.threshold, invoice.paid, audit.alert, batch.completed and fine_tuning.completed. Return a 2xx quickly and process the event asynchronously; deliveries are at-least-once, so handlers must tolerate duplicates. Events tied to endpoints the docs still list as coming soon depend on the roadmap, so confirm availability before building on them.
Security and reliability patterns
Patterns that keep the integration small and defensible:
- Verify signatures before parsing and keep an append-only record of deliveries.
- Route audit.alert and key.rotated to the agency logging platform.
- Minimise payload content and fetch detail under existing access controls.
- In air-gapped environments, use internal event pipelines instead of external webhooks.
Putting webhooks to work
Send audit.alert and key.rotated events into the agency logging platform, keep an append-only record, and treat model.deprecated as a migration trigger for citizen-facing services.
Start from the events that protect revenue and access: quota.warning, quota.exceeded, key.rotated and audit.alert. Add model.deprecated and usage.threshold as you automate more. The integration surface is small — one endpoint, one signature check, one idempotent handler — and the request path stays OpenAI-compatible, so nothing about your API calls changes. Self-serve plans are flat monthly with unlimited fair-use usage and no per-token billing; current plans are on the pricing page. Prototype on the free plan and use the 14-day full-access trial when you need larger models.
Honest comparison
| Factor | Plugsky webhooks | Polling the API | Building an event bus in-house |
|---|---|---|---|
| Delivery model | Push, HTTPS, HMAC-SHA256 signed | Pull on a schedule | You design and operate it |
| Event coverage | Nine platform event types | Whatever you remember to query | Only what you instrument |
| Ops overhead | Low — endpoint plus handler | Low but laggy | High — queues, retries, on-call |
| Reaction time | Seconds after the event | Next poll interval | Depends on your pipeline |
| Audit path | audit.alert plus SIEM export | Manual log queries | You build the trail |
| Time to integrate | Hours | Hours | Weeks |
Frequently asked questions
Do webhooks work in an air-gapped environment?
No external webhook deliveries are possible without egress. In air-gapped deployments, route the same event signals through your internal event bus and log pipeline.
Can we keep using the OpenAI SDK?
Yes. The request path stays OpenAI-compatible, so you change the base URL and model names and keep your existing SDK code, prompts and evaluations.
How do I verify a webhook signature?
Compute an HMAC-SHA256 over the raw request body with your signing secret and compare it to the signature header in constant time before parsing the payload.
What happens if our endpoint is down?
Delivery is at-least-once and retried, so events may arrive again after recovery. Keep a dead-letter queue, alert on repeated failures, and make handlers idempotent.
Can deliveries be duplicated or reordered?
Treat delivery as at-least-once: deduplicate by event identity and process per entity where order matters rather than assuming a strict global sequence.
What should the endpoint return?
Return a 2xx quickly before doing the work, then process the event asynchronously so a slow downstream job cannot cause retries.
How is pricing structured?
Webhooks are part of the platform: self-serve plans are flat monthly with unlimited fair-use usage and no per-token billing. See the live pricing page for current plans.
Is there a free plan?
Yes — the free plan includes plugsky-micro and plugsky-lite with no credit card, and a 14-day full-access trial covers larger models.