Developers
Developer API webhooks
Receive seal.created, seal.completed, seal.revoked, and seal.paid notifications on your HTTPS endpoint. Manage endpoints in the authenticated Developer console with the webhooks:manage scope.
When to use webhooks
Webhooks fit integrations that react to seal lifecycle changes without polling GET /api/v1/verify/{code}. They require Business, Enterprise, or an entitled custom plan with Developer API access.
API keys remain the primary auth model for /api/v1. Webhooks are optional notifications layered on top of your existing upload → seal → verify workflow.
Event types
seal.created — a seal record exists and processing may still be in flight.
seal.completed — sealing finished successfully; verification code is ready for recipients.
seal.revoked — the issuer revoked the seal; treat public verify as revoked.
seal.paid — invoice payment state changed where thin invoicing is enabled for the workspace.
Register and manage endpoints
Sign in to the Opcilo app as a workspace admin with Developer entitlement. Open Developer → Webhooks to register an HTTPS URL, choose subscribed events, and rotate signing secrets.
Programmatic management uses JWT-authenticated /api/developer routes with the webhooks:manage scope on your workspace API key where applicable. Plaintext signing secrets are shown once at creation — store them in a secret manager.
HTTPS and SSRF requirements
Webhook URLs must use HTTPS on the public internet. Opcilo validates URLs at connect time and blocks private, link-local, and metadata IP ranges to prevent SSRF against your integration infrastructure.
Do not point webhooks at localhost, RFC1918 addresses, or cloud metadata endpoints. Use a tunnel or staging host with a valid TLS certificate during development.
Verify HMAC signatures
Each delivery includes X-Opcilo-Timestamp, X-Opcilo-Event-Id, X-Opcilo-Event (event type), and X-Opcilo-Signature. The signature is HMAC-SHA-256 over the canonical string timestamp.eventId.rawBody using your endpoint signing secret.
Compare signatures in constant time. Reject requests with stale timestamps to limit replay windows. Rotate signing secrets in the Developer console after any leak and update your verifier promptly.
Delivery semantics
Delivery is at-least-once: the same logical event keeps a stable X-Opcilo-Event-Id so your handler can deduplicate safely. Respond with 2xx quickly; Opcilo schedules retries with backoff for transient failures.
Detailed payload fields are documented in the Development OpenAPI document (GET /openapi/developer-v1.json). Pin integrations against Dev OpenAPI or an exported snapshot — not Production hosts.