scriptivox 0.1.0__py3-none-any.whl

scriptivox/_types.py

@@ -0,0 +1,473 @@
+# GENERATED by scripts/generate.py from openapi/openapi.json — do not edit by hand.
+# OpenAPI 1.0.0 · sha256 489f83bddaa9893f
+"""Response and request shapes of the Scriptivox API, as TypedDicts (plain dicts at runtime)."""
+from __future__ import annotations
+
+from typing import Any, Dict, List, Literal, Optional, TypedDict, Union
+
+class _ErrorDetailRequired(TypedDict):
+    #: Machine-readable error code.
+    code: Literal["INVALID_REQUEST", "INVALID_FILENAME", "INVALID_MEDIA_FORMAT", "FILE_NOT_UPLOADED", "FILE_TOO_LARGE", "UPLOAD_ALREADY_USED", "UPLOAD_EXPIRED", "INVALID_API_KEY", "API_KEY_REVOKED", "INSUFFICIENT_BALANCE", "ZERO_BALANCE", "UPLOAD_NOT_FOUND", "TRANSCRIPTION_NOT_FOUND", "NOT_FOUND", "FORBIDDEN", "METHOD_NOT_ALLOWED", "CONFLICT", "PAYLOAD_TOO_LARGE", "UNSUPPORTED_MEDIA_TYPE", "IDEMPOTENCY_KEY_LOCKED", "IDEMPOTENCY_KEY_CONFLICT", "RATE_LIMIT_EXCEEDED", "INTERNAL_ERROR", "MAINTENANCE", "ENDPOINT_REMOVED", "ISSUER_UNCONFIGURED"]
+    #: Human-readable description of what went wrong.
+    message: str
+
+
+class ErrorDetail(_ErrorDetailRequired, total=False):
+    """The error envelope. Always present on a failed request."""
+    #: Documentation for this error code.
+    docs_url: str
+    #: The id of this request, the same value as the `X-Request-Id` response header. Include it when you contact support.
+    request_id: str
+
+
+class _ErrorRequired(TypedDict):
+    #: The error envelope. Always present on a failed request.
+    error: ErrorDetail
+
+
+class Error(_ErrorRequired, total=False):
+    """Every failed request returns this shape. `code` is stable and machine-readable; `message` is a sanitized, customer-safe string and never a raw stack trace; `request_id` identifies the request for support."""
+    #: Seconds to wait before retrying. Present on 429 responses alongside the Retry-After header.
+    retry_after: int
+
+
+class CreateUploadRequest(TypedDict):
+    #: Name of the file being uploaded, e.g. "meeting.mp3". ASCII only, no path separators, and it must carry a supported extension.
+    filename: str
+
+
+class Upload(TypedDict):
+    #: Pass this to POST /v1/transcribe once the PUT succeeds.
+    upload_id: str
+    #: Presigned URL to PUT the file bytes to.
+    upload_url: str
+    #: Seconds until upload_url expires. Currently 3600.
+    expires_in: int
+    #: HTTP method to use against upload_url.
+    method: Literal["PUT"]
+    #: Headers that must be sent with the PUT request.
+    headers: Dict[str, str]
+
+
+class _CreateTranscriptionFromUrlRequired(TypedDict):
+    #: Anonymously accessible http or https URL. An anonymous GET must return the raw file bytes, not an HTML preview, login form or password page. Direct and presigned URLs (S3, GCS, Azure SAS) always work. Share links work only when set to "anyone with the link can view": Google Drive, Dropbox files (not /scl/fo/ folder links), and OneDrive personal /redir or onedrive.live.com links. OneDrive 1drv.ms/v/c/ and /p/c/ photo shares cannot be used — Microsoft routes them through SharePoint Photos, which requires sign-in.
+    url: str
+
+
+class CreateTranscriptionFromUrl(_CreateTranscriptionFromUrlRequired, total=False):
+    """Transcribe a file we download from a public URL."""
+    #: ISO 639-1 language code (with BCP-47 fallbacks such as `yue` and `kea`), e.g. "en", "es", "fr". Omit or pass null for auto-detection. Passing the language explicitly is recommended: it is faster (the model skips its detection pass) and avoids known auto-detect failure modes on short clips, code-switched audio, and files that open with music. Forcing a language the audio is not in can produce a translation rather than a transcription. Invalid codes return 400 INVALID_REQUEST.
+    language: Optional[str]
+    #: Identify who said what and attach a speaker label to every utterance. Implies align: true, because speaker assignment needs word-level alignment.
+    diarize: bool
+    #: Expected number of speakers. Requires diarize: true; passing it without diarize returns 400 INVALID_REQUEST. This is a soft prior, not a hard ceiling — the result may contain slightly more or fewer labels. Strongly recommended whenever the count is known: it measurably reduces over- and under-segmentation.
+    speaker_count: int
+    #: Produce word-level start/end timestamps plus per-word confidence where the alignment model supports it. Confidence is language-dependent and may be null. Ignored (treated as true) when diarize is true.
+    align: bool
+    #: URL to receive the job's webhooks (processing, then completed or failed). Must be https://. Signed with the key's webhook signing secret and retried with backoff until your server answers 2xx — see https://platform.scriptivox.com/docs/webhooks.
+    webhook_url: str
+
+
+class _CreateTranscriptionFromUploadRequired(TypedDict):
+    #: The upload_id returned by POST /v1/upload.
+    upload_id: str
+
+
+class CreateTranscriptionFromUpload(_CreateTranscriptionFromUploadRequired, total=False):
+    """Transcribe a file previously sent to a presigned upload URL."""
+    #: ISO 639-1 language code (with BCP-47 fallbacks such as `yue` and `kea`), e.g. "en", "es", "fr". Omit or pass null for auto-detection. Passing the language explicitly is recommended: it is faster (the model skips its detection pass) and avoids known auto-detect failure modes on short clips, code-switched audio, and files that open with music. Forcing a language the audio is not in can produce a translation rather than a transcription. Invalid codes return 400 INVALID_REQUEST.
+    language: Optional[str]
+    #: Identify who said what and attach a speaker label to every utterance. Implies align: true, because speaker assignment needs word-level alignment.
+    diarize: bool
+    #: Expected number of speakers. Requires diarize: true; passing it without diarize returns 400 INVALID_REQUEST. This is a soft prior, not a hard ceiling — the result may contain slightly more or fewer labels. Strongly recommended whenever the count is known: it measurably reduces over- and under-segmentation.
+    speaker_count: int
+    #: Produce word-level start/end timestamps plus per-word confidence where the alignment model supports it. Confidence is language-dependent and may be null. Ignored (treated as true) when diarize is true.
+    align: bool
+    #: URL to receive the job's webhooks (processing, then completed or failed). Must be https://. Signed with the key's webhook signing secret and retried with backoff until your server answers 2xx — see https://platform.scriptivox.com/docs/webhooks.
+    webhook_url: str
+
+
+# Supply exactly one of `url` (Scriptivox downloads the file) or `upload_id` (returned by POST /v1/upload). Every other property is optional and shared by both forms.
+CreateTranscriptionRequest = Union[CreateTranscriptionFromUrl, CreateTranscriptionFromUpload]
+
+
+class _TranscriptionCreatedRequired(TypedDict):
+    #: Transcription id. Pass it to GET /v1/transcribe/{id} to poll for the result.
+    id: str
+    #: Always "created" here. The file has been accepted but not yet downloaded or validated, so this is not a statement that the input is usable.
+    status: Literal["created"]
+
+
+class TranscriptionCreated(_TranscriptionCreatedRequired, total=False):
+    #: Human-readable confirmation. Not machine-readable; do not branch on it.
+    message: str
+
+
+class TranscriptionError(TypedDict):
+    """Present when status is "failed". These codes surface only on GET /v1/transcribe/{id}, never on the submit call. Failed jobs are free — the reservation is released."""
+    #: Stable machine-readable reason the job failed. Branch on this, never on message.
+    code: Literal["URL_NOT_ACCESSIBLE", "DOWNLOAD_FAILED", "INVALID_MEDIA_FORMAT", "FILE_TOO_LARGE", "DURATION_TOO_LONG", "INSUFFICIENT_BALANCE", "PROCESSING_ERROR", "CREATED_TIMEOUT", "DOWNLOAD_TIMEOUT", "PROCESSING_TIMEOUT", "BILLING_ERROR", "INTERNAL_ERROR", "CANCELLED"]
+    #: Human-readable explanation. Wording may change between releases.
+    message: str
+
+
+class _TranscriptionCancelledRequired(TypedDict):
+    #: The transcription that was cancelled.
+    id: str
+    #: A cancelled job is reported as "failed" with error.code CANCELLED — there is no separate "cancelled" status.
+    status: Literal["failed"]
+
+
+class TranscriptionCancelled(_TranscriptionCancelledRequired, total=False):
+    error: TranscriptionError
+    #: Kept for compatibility, always 0: nothing is reserved before transcription starts, and a job can only be cancelled before then.
+    released_cents: float
+
+
+# created: accepted, about to download or validate. downloading: URL flow only. processing: being transcribed. completed: result is populated. failed: inspect error.code.
+TranscriptionStatus = Literal["created", "downloading", "pending", "processing", "completed", "failed"]
+
+
+class Word(TypedDict, total=False):
+    """Present only when align is effectively true. Leading whitespace is stripped — reconstruct spacing from utterance.text if you need it exactly."""
+    #: The token as transcribed, including any trailing punctuation.
+    word: str
+    #: Seconds from the start of the audio.
+    start: float
+    #: Seconds from the start of the audio.
+    end: float
+    #: Null for languages whose alignment model does not report confidence. Handle null defensively.
+    confidence: Optional[float]
+    #: Absent when diarize is false.
+    speaker: str
+
+
+class Utterance(TypedDict, total=False):
+    #: Seconds from the start of the audio to the first word.
+    start: float
+    #: Seconds from the start of the audio to the last word.
+    end: float
+    #: The utterance as a single string, with original spacing.
+    text: str
+    #: Labels are "SPEAKER 1", "SPEAKER 2", ... (space, 1-indexed). Null when diarize is false.
+    speaker: Optional[str]
+    #: Mean word confidence for this utterance. Null for languages whose alignment model does not report it.
+    confidence: Optional[float]
+    #: Empty array when align is false.
+    words: List[Word]
+
+
+class TranscriptionResult(TypedDict, total=False):
+    """Populated once status is "completed"."""
+    #: The whole transcript as one string, utterances joined in order.
+    full_transcript: str
+    #: The language actually used, detected or supplied.
+    language: str
+    #: Length of the decoded audio in seconds.
+    duration_seconds: float
+    #: Null when diarize is false.
+    speakers: Optional[List[str]]
+    #: Speech segments in chronological order. This is the structure to iterate; full_transcript is a convenience.
+    utterances: List[Utterance]
+
+
+class _TranscriptionSummaryRequired(TypedDict):
+    #: Transcription id, as returned by POST /v1/transcribe.
+    id: str
+    status: TranscriptionStatus
+
+
+class TranscriptionSummary(_TranscriptionSummaryRequired, total=False):
+    """A transcription without its transcript. This is what GET /v1/transcriptions returns per item."""
+    #: Rounded to the nearest whole second. Null until the file has been probed.
+    audio_duration_seconds: Optional[int]
+    #: Size of the source file. Null until it has been downloaded.
+    file_size_bytes: Optional[int]
+    #: ISO code of the language used. Null until detection has run.
+    language: Optional[str]
+    #: Whether speaker diarization was requested for this job.
+    diarize: bool
+    #: The speaker count supplied on the request, not a detected one. Null when it was not supplied.
+    speaker_count: Optional[int]
+    #: The effective value. Always true when diarize is true, even if the request passed align: false.
+    align: bool
+    #: Fractional and exact, e.g. 0.061111 for an 11-second clip at $0.20/hour. The balance is debited against this precise value, not a rounded one.
+    cost_cents: Optional[float]
+    #: Present only on URL-flow transcriptions.
+    source_url: str
+    #: Free-text stage label while processing, e.g. "downloading". For display only — the machine-readable state is status.
+    progress: Optional[str]
+    #: When the job was accepted. RFC 3339, UTC.
+    created_at: str
+    #: When transcription began. Null while the job is still queued.
+    started_at: Optional[str]
+    #: When the job reached a terminal state. Null until then.
+    completed_at: Optional[str]
+    error: TranscriptionError
+
+
+class Transcription(TranscriptionSummary, total=False):
+    """A transcription including its result once complete. Some result fields depend on the flags the job was created with: result.speakers and utterances[].speaker are null when diarize is false, and utterances[].words is empty when align is false."""
+    #: Null until status is "completed".
+    result: Optional[TranscriptionResult]
+
+
+class TranscriptionPage(TypedDict):
+    #: This page of transcriptions, newest first unless order says otherwise. Each item omits the heavy result object.
+    items: List[TranscriptionSummary]
+    #: Pass back as the cursor query parameter for the next page. Null on the last page.
+    next_cursor: Optional[str]
+
+
+class ServiceDiscoveryEndpointsItem(TypedDict, total=False):
+    #: HTTP method.
+    method: str
+    #: Path, including the /v1 prefix.
+    path: str
+    #: What the operation does.
+    summary: str
+
+
+class _ServiceDiscoveryRequired(TypedDict):
+    #: Human-readable name of the API.
+    service: str
+    #: The API version this host serves, matching the URL prefix.
+    version: str
+    #: Prefix every path in `endpoints` with this.
+    base_url: str
+    #: Human-readable documentation index.
+    documentation: str
+    #: This document.
+    openapi: str
+
+
+class ServiceDiscovery(_ServiceDiscoveryRequired, total=False):
+    """What GET /v1 returns. Deliberately loose: it is a signpost for an agent that has just found this host, not a contract to generate a client from. The authoritative description of every operation is this document."""
+    #: One sentence on what the API does.
+    description: str
+    #: What the service is for, and when not to use it.
+    llms_txt: str
+    #: Model Context Protocol manifest, for agents that call tools natively.
+    mcp: str
+    #: Live uptime and incident history.
+    status: str
+    #: How to authenticate every other operation: the scheme, the accepted headers, the key format, and where a human gets one.
+    authentication: Dict[str, Any]
+    #: One entry per operation, with method, path and a one-line summary.
+    endpoints: List[ServiceDiscoveryEndpointsItem]
+    #: Per-IP and per-key ceilings, the header names that carry them, and where they are documented.
+    rate_limits: Dict[str, Any]
+    #: Versioning scheme, current version, policy URL, and the headers a deprecation would arrive on.
+    versioning: Dict[str, Any]
+    #: The error envelope, and where the code list lives.
+    errors: Dict[str, Any]
+
+
+class FeedbackRequest(TypedDict, total=False):
+    #: How good the transcript is, 1 (poor) to 5 (excellent). Completed jobs only.
+    rating: int
+    #: What the rating is about.
+    topics: List[Literal["accuracy", "speakers", "timing", "language", "formatting", "other"]]
+    #: A short comment on the transcript.
+    comment: str
+    #: Your end user's own words, unchanged, if you have them.
+    their_words: str
+    #: true to report a problem with this job (failed, empty or wrong). Needs what_happened.
+    problem: bool
+    #: What went wrong, for a problem report.
+    what_happened: str
+
+
+class FeedbackResultProblemReport(TypedDict, total=False):
+    """The problem report opened or added to, or null."""
+    #: The report id (null if a parallel call opened it a moment earlier).
+    id: Optional[str]
+    #: Open until the team resolves it (within 24 hours).
+    status: Literal["open"]
+    #: True when this was added to a report on the same job that is still open.
+    added_to_open_report: bool
+    #: True when a rating of 1 or 2 with words opened it.
+    opened_by_rating: bool
+
+
+class _FeedbackResultRequired(TypedDict):
+    #: The job the feedback is about.
+    transcription_id: str
+    #: True when a rating was sent and saved.
+    rating_saved: bool
+    #: The problem report opened or added to, or null.
+    problem_report: Optional[FeedbackResultProblemReport]
+
+
+class FeedbackResult(_FeedbackResultRequired, total=False):
+    #: Set when the rating was saved but the problem report was not (for example the daily limit).
+    problem_report_error: str
+
+
+class WebhookTestRequest(TypedDict, total=False):
+    #: Where to send the test event. https:// only. Without it, the account's default webhook URL is used.
+    url: str
+
+
+class _WebhookSendResultRequired(TypedDict):
+    #: The X-Scriptivox-Delivery id of this event.
+    delivery_id: str
+    #: The event sent.
+    event: str
+    #: The X-Scriptivox-Attempt value of this try.
+    attempt: int
+    #: True when your server answered with a 2xx status.
+    delivered: bool
+    #: The HTTP status your server answered, or null when there was no answer.
+    response_code: Optional[int]
+    #: Why it was not delivered, e.g. "HTTP 500" or "No answer within 10 s.".
+    error: Optional[str]
+    #: How long the try took.
+    duration_ms: int
+    #: The event after this try: pending (automatic retries continue), succeeded, failed (no tries left, or 410), superseded.
+    status: Literal["pending", "succeeded", "failed", "superseded", "unknown"]
+
+
+class WebhookSendResult(_WebhookSendResultRequired, total=False):
+    """What happened to one try of a webhook made on request."""
+    #: The job (resend only).
+    transcription_id: str
+    #: Where the test event went (test only).
+    url: str
+    #: When the next automatic retry is due, if any.
+    next_attempt_at: Optional[str]
+
+
+class _WebhookTranscriptionProcessingRequired(TypedDict):
+    #: The event name.
+    event: Literal["transcription.processing"]
+    #: The job this event is about.
+    transcription_id: str
+    #: The job status when the event was made.
+    status: Literal["processing"]
+
+
+class WebhookTranscriptionProcessing(_WebhookTranscriptionProcessingRequired, total=False):
+    #: Measured length of the audio.
+    duration_seconds: float
+    #: Reserved for this job, in cents; charged when it completes.
+    cost_cents: float
+
+
+class _WebhookTranscriptionCompletedRequired(TypedDict):
+    #: The event name.
+    event: Literal["transcription.completed"]
+    #: The job this event is about.
+    transcription_id: str
+    #: The job status when the event was made.
+    status: Literal["completed"]
+    #: The transcript, the same as GET /v1/transcribe/{id} returns.
+    result: TranscriptionResult
+
+
+class WebhookTranscriptionCompleted(_WebhookTranscriptionCompletedRequired, total=False):
+    #: Billed length of the audio.
+    duration_seconds: float
+    #: Charged for this job, in cents.
+    cost_cents: float
+
+
+class WebhookTranscriptionFailed(TypedDict):
+    #: The event name.
+    event: Literal["transcription.failed"]
+    #: The job this event is about.
+    transcription_id: str
+    #: The job status when the event was made.
+    status: Literal["failed"]
+    #: Why the job failed. Branch on error.code.
+    error: TranscriptionError
+
+
+class WebhookTranscriptionDownloading(TypedDict):
+    #: The event name.
+    event: Literal["transcription.downloading"]
+    #: The job this event is about.
+    transcription_id: str
+    #: The job status when the event was made.
+    status: Literal["downloading"]
+
+
+class _WebhookTestRequired(TypedDict):
+    #: The event name.
+    event: Literal["webhook.test"]
+    #: Always true: this is not about a real job.
+    test: Literal[True]
+    #: A fixed sentence saying this is a test.
+    message: str
+
+
+class WebhookTest(_WebhookTestRequired, total=False):
+    #: When the test was requested.
+    created_at: str
+
+
+class AutoTopup(TypedDict):
+    """Auto top-up, set on the Billing page of the API dashboard. When on and available_cents falls below threshold_cents, the saved card is charged amount_cents, up to the monthly limit set there. A top-up shows on a later call, not this one."""
+    #: Whether auto top-up is on.
+    enabled: bool
+    #: Top up when available_cents falls below this, in cents.
+    threshold_cents: int
+    #: How much each top-up adds, in cents.
+    amount_cents: int
+
+
+class _BalanceRequired(TypedDict):
+    #: Total balance, in cents. Can be below zero after a refunded deposit.
+    balance_cents: float
+    #: Held against in-progress transcriptions, in cents.
+    reserved_cents: float
+    #: balance_cents minus reserved_cents. Must be above zero to start a job.
+    available_cents: float
+    #: Current price per hour of audio, in cents.
+    price_per_hour_cents: float
+    #: Auto top-up, set on the Billing page of the API dashboard. When on and available_cents falls below threshold_cents, the saved card is charged amount_cents, up to the monthly limit set there. A top-up shows on a later call, not this one.
+    auto_topup: AutoTopup
+
+
+class Balance(_BalanceRequired, total=False):
+    #: available_cents divided by price_per_hour_cents.
+    estimated_hours_available: float
+    #: Where a human can add funds. Send a user here on a 402.
+    deposit_url: str
+    #: When the balance last changed. RFC 3339, UTC.
+    updated_at: str
+
+
+__all__ = [
+    "AutoTopup",
+    "Balance",
+    "CreateTranscriptionFromUpload",
+    "CreateTranscriptionFromUrl",
+    "CreateTranscriptionRequest",
+    "CreateUploadRequest",
+    "Error",
+    "ErrorDetail",
+    "FeedbackRequest",
+    "FeedbackResult",
+    "FeedbackResultProblemReport",
+    "ServiceDiscovery",
+    "ServiceDiscoveryEndpointsItem",
+    "Transcription",
+    "TranscriptionCancelled",
+    "TranscriptionCreated",
+    "TranscriptionError",
+    "TranscriptionPage",
+    "TranscriptionResult",
+    "TranscriptionStatus",
+    "TranscriptionSummary",
+    "Upload",
+    "Utterance",
+    "WebhookSendResult",
+    "WebhookTest",
+    "WebhookTestRequest",
+    "WebhookTranscriptionCompleted",
+    "WebhookTranscriptionDownloading",
+    "WebhookTranscriptionFailed",
+    "WebhookTranscriptionProcessing",
+    "Word",
+]

scriptivox/_version.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

scriptivox/_webhooks.py

@@ -0,0 +1,108 @@
+"""Webhook signature check. The signing formula (platform.scriptivox.com/docs/webhooks)::
+
+    signature = hex(HMAC-SHA256(secret, f"{X-Scriptivox-Timestamp}.{raw body}"))
+
+where ``secret`` is the key's whole ``whsec_…`` string. A timestamp more than 5 minutes from now is refused.
+"""
+from __future__ import annotations
+
+import hashlib
+import hmac
+import json
+import time
+from typing import Any, Iterable, Mapping, Optional, Tuple, Union, cast
+
+from ._exceptions import WebhookVerificationError
+from ._types import WebhookTest, WebhookTranscriptionCompleted, WebhookTranscriptionDownloading, WebhookTranscriptionFailed, WebhookTranscriptionProcessing
+
+SIGNATURE_HEADER = "X-Scriptivox-Signature"
+TIMESTAMP_HEADER = "X-Scriptivox-Timestamp"
+DELIVERY_HEADER = "X-Scriptivox-Delivery"
+ATTEMPT_HEADER = "X-Scriptivox-Attempt"
+#: Seconds a webhook's timestamp may be away from now.
+DEFAULT_TOLERANCE = 300
+
+#: Every event body a webhook can carry; switch on ``event``. Answer 2xx to event types you do not know.
+WebhookEvent = Union[
+    WebhookTranscriptionProcessing,
+    WebhookTranscriptionCompleted,
+    WebhookTranscriptionFailed,
+    WebhookTranscriptionDownloading,
+    WebhookTest,
+]
+
+HeadersLike = Union[Mapping[str, Any], Iterable[Tuple[str, str]]]
+
+
+def read_header(headers: HeadersLike, name: str) -> Optional[str]:
+    """Case-insensitive lookup in a dict, httpx/Starlette/Django/Flask headers, or a list of pairs."""
+    wanted = name.lower()
+    items = headers.items() if hasattr(headers, "items") else headers
+    for key, value in cast(Iterable[Tuple[str, Any]], items):
+        if isinstance(key, bytes):
+            key = key.decode("latin-1")
+        if key.lower() != wanted or value is None:
+            continue
+        if isinstance(value, (list, tuple)):
+            value = value[0] if value else None
+        if isinstance(value, bytes):
+            value = value.decode("latin-1")
+        return None if value is None else str(value)
+    return None
+
+
+def _body_bytes(raw_body: Union[bytes, bytearray, memoryview, str]) -> bytes:
+    if isinstance(raw_body, str):
+        return raw_body.encode("utf-8")
+    if isinstance(raw_body, (bytes, bytearray, memoryview)):
+        return bytes(raw_body)
+    raise TypeError(
+        "verify_webhook needs the raw request body (bytes or str), not parsed JSON: "
+        "re-serialising changes the bytes and the signature."
+    )
+
+
+def compute_signature(raw_body: Union[bytes, bytearray, memoryview, str], timestamp: str, secret: str) -> str:
+    """The signature the API would send for this body and timestamp."""
+    mac = hmac.new(secret.encode("utf-8"), f"{timestamp}.".encode("utf-8"), hashlib.sha256)
+    mac.update(_body_bytes(raw_body))
+    return mac.hexdigest()
+
+
+def verify_webhook(
+    raw_body: Union[bytes, bytearray, memoryview, str],
+    headers: HeadersLike,
+    secret: str,
+    *,
+    tolerance: int = DEFAULT_TOLERANCE,
+    now: Optional[float] = None,
+) -> WebhookEvent:
+    """Check that a webhook request came from Scriptivox and is fresh, then return its parsed event.
+
+    Pass the body exactly as received (``await request.body()``, ``request.get_data()``,
+    ``request.body``), never re-serialised JSON. Raises WebhookVerificationError; answer such a
+    request with 400. Deduplicate on the X-Scriptivox-Delivery header: an event can arrive twice.
+    """
+    body = _body_bytes(raw_body)
+    if not isinstance(secret, str) or not secret:
+        raise TypeError("verify_webhook needs the key's webhook signing secret (whsec_…).")
+    signature = read_header(headers, SIGNATURE_HEADER)
+    timestamp = read_header(headers, TIMESTAMP_HEADER)
+    if not signature or not timestamp:
+        raise WebhookVerificationError("missing_header", "Missing X-Scriptivox-Signature or X-Scriptivox-Timestamp header.")
+    timestamp = timestamp.strip()
+    if not timestamp.isdigit():
+        raise WebhookVerificationError("invalid_timestamp", "X-Scriptivox-Timestamp is not a Unix time in seconds.")
+    current = time.time() if now is None else now
+    if abs(int(current) - int(timestamp)) > tolerance:
+        raise WebhookVerificationError(
+            "timestamp_outside_tolerance",
+            f"The webhook's timestamp is more than {tolerance} s from now: refused as a possible replay.",
+        )
+    expected = compute_signature(body, timestamp, secret)
+    if not hmac.compare_digest(expected.encode("ascii"), signature.strip().lower().encode("utf-8")):
+        raise WebhookVerificationError("signature_mismatch", "The webhook signature does not match: wrong secret, or the body was changed.")
+    try:
+        return cast(WebhookEvent, json.loads(body.decode("utf-8")))
+    except (ValueError, UnicodeDecodeError):
+        raise WebhookVerificationError("invalid_json", "The webhook body is not JSON.") from None