Verify events before acting on them

Setup and events

An organization manager can add a public HTTPS endpoint in the console, select events, inspect attempts, send a test event, disable delivery, and rotate its signing secret. Save the secret immediately: it is shown once. The receiver must use port 443 and cannot redirect to another destination. Private addresses, IP literals, credentials in URLs, query strings and fragments are rejected.

Events include extraction.queued, extraction.processing, extraction.succeeded, extraction.partially_succeeded, extraction.failed, extraction.cancelled, credit.threshold_reached, credit.exhausted and webhook.test.

Version 1 envelope

The immutable JSON envelope contains id, type, version (1), resource_id, created_at and event-specific data. Use GET /extractions/{id} as the source of truth for current extraction state.

Verify the exact request bytes

1. Read PDFScribe-Event-ID, PDFScribe-Key-Version and PDFScribe-Signature. The signature format is t=UNIX_SECONDS,v1=LOWERCASE_HEX.
2. Reject timestamps more than five minutes in the past or future.
3. Decode your signing secret using unpadded standard Base64. Compute HMAC-SHA256 over the event ID, a literal period, the decimal timestamp, another period, and the exact raw HTTP body bytes. Do not parse and reserialize JSON before checking.
4. Compare the expected hexadecimal MAC using a constant-time comparison. Verify the envelope ID agrees with the header and accept only supported event types and versions.
5. Persist the event ID with your processing decision to deduplicate retries and manual replays. Return a 2xx after safely accepting the event.

Retries and rotation

Delivery has bounded retry and replay budgets. A timeout can follow successful receipt, so duplicates remain possible. Inspect attempts for the stable outcome code; do not infer success from a queued test. Manual replay preserves the original event ID and payload. Rotation immediately replaces the signing key without a grace period; retries use the current key and key-version header. Coordinate receiver configuration before rotating.

Credit notifications

Configure two to four increasing consumed-percentage warning thresholds from 1 through 99; defaults are 50 and 90. Exhaustion at 100% is mandatory and does not occupy a warning slot. Optional email warnings may be disabled; exhaustion remains mandatory. Notifications are deduplicated per balance cycle and threshold.

Never log signing secrets, bearer keys, signed upload URLs or document contents. Use extraction and request IDs for investigation.