trueppm-api 0.4.0__py3-none-any.whl

trueppm_api/apps/webhooks/migrations/0009_encrypt_webhook_secret_and_failure_counters.py

@@ -0,0 +1,100 @@
+# Generated by Django 5.2.16 on 2026-08-17 14:09
+#
+# Hand-ordered (#2885): the generated migration emitted RemoveField(secret) first,
+# which would have dropped every signing secret in the install. The AddField must
+# come first, the RunPython copies the plaintext into the new encrypted column
+# while both exist, and only then is the plaintext column dropped. The data step
+# lives in webhooks/backfill.py so a test can exercise it without importing this
+# module by name (CLAUDE.md migration rule 3).
+
+from django.db import migrations, models
+
+from trueppm_api.apps.webhooks.backfill import (
+    encrypt_webhook_secrets,
+    reverse_encrypt_webhook_secrets,
+)
+
+
+class Migration(migrations.Migration):
+    dependencies = [
+        ("webhooks", "0008_risk_baseline_comment_events"),
+    ]
+
+    operations = [
+        migrations.AddField(
+            model_name="webhook",
+            name="secret_ciphertext",
+            field=models.BinaryField(blank=True, default=b""),
+        ),
+        # elidable: safe for the optimizer to drop IF this migration's originals
+        # ship and run in a released version before the squash that replaces them
+        # is generated — a squash only guarantees an empty table for ops whose
+        # originals already applied in an earlier release (#4320 correction; see
+        # CLAUDE.md migration-discipline rule 1/6 and access/migrations/
+        # 0017_viewer_ordinal_one.py for the upgrade-path counterexample this was
+        # wrong about). As of this writing 0009 is UNRELEASED, so that condition
+        # does not yet hold: whichever 0.x squash first spans this migration will
+        # run it directly against populated tables on upgrade, exactly like the
+        # access squash did. Re-check this comment, and verify with a test in the
+        # shape of tests/apps/access/test_viewer_ordinal_upgrade.py, before that
+        # squash is generated — do not assume elision is still safe by then.
+        # Leaving it non-elidable would make squashmigrations keep it as an
+        # optimizer barrier, pinning the add-copy-drop dance for a column no model
+        # has — plus a hard import of webhooks.backfill — into the baseline.
+        migrations.RunPython(
+            encrypt_webhook_secrets,
+            reverse_encrypt_webhook_secrets,
+            elidable=True,
+        ),
+        # State-only, and a no-op forward: `blank`/`default` are not DDL in Django.
+        # It exists for the REVERSE direction. RemoveField's backwards pass re-adds
+        # the field from the previous state, where `secret` was CharField(max_length=255)
+        # with no default and blank=False — so Django emits a bare
+        # `ADD COLUMN "secret" varchar(255) NOT NULL`, which PostgreSQL rejects on any
+        # table with rows ("contains null values"). That aborts the reverse *before*
+        # reverse_encrypt_webhook_secrets can put the plaintext back, on exactly the
+        # databases that have webhooks. Declaring blank/default here makes the
+        # re-added column carry `DEFAULT ''`. (Passing `field=` to RemoveField would
+        # not work: its database_backwards reads the field off to_state.)
+        migrations.AlterField(
+            model_name="webhook",
+            name="secret",
+            field=models.CharField(blank=True, default="", max_length=255),
+        ),
+        migrations.RemoveField(
+            model_name="webhook",
+            name="secret",
+        ),
+        migrations.AddField(
+            model_name="webhook",
+            name="consecutive_failures",
+            field=models.PositiveIntegerField(
+                default=0,
+                help_text="Terminal delivery failures since the last success. Resets to 0 on any successful delivery.",
+            ),
+        ),
+        migrations.AddField(
+            model_name="webhook",
+            name="disabled_at",
+            field=models.DateTimeField(
+                blank=True,
+                help_text="When the automatic failure guard deactivated this subscription. Null when it is active, or when an admin deactivated it by hand.",
+                null=True,
+            ),
+        ),
+        migrations.AddField(
+            model_name="webhook",
+            name="disabled_reason",
+            field=models.CharField(blank=True, default="", max_length=255),
+        ),
+        migrations.AddField(
+            model_name="webhook",
+            name="last_failure_at",
+            field=models.DateTimeField(blank=True, null=True),
+        ),
+        migrations.AddField(
+            model_name="webhook",
+            name="last_failure_reason",
+            field=models.CharField(blank=True, default="", max_length=255),
+        ),
+    ]

trueppm_api/apps/webhooks/migrations/0010_alter_webhook_disabled_at.py

@@ -0,0 +1,21 @@
+# Generated by Django 5.2.17 on 2026-10-17 11:36
+
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+    dependencies = [
+        ("webhooks", "0009_encrypt_webhook_secret_and_failure_counters"),
+    ]
+
+    operations = [
+        migrations.AlterField(
+            model_name="webhook",
+            name="disabled_at",
+            field=models.DateTimeField(
+                blank=True,
+                help_text="When the automatic failure guard, or a credential-revocation sweep (password reset, off-boarding, or revoke_api_tokens --all), deactivated this subscription. Null when it is active, or when an admin deactivated it by hand.",
+                null=True,
+            ),
+        ),
+    ]

trueppm_api/apps/webhooks/migrations/0011_webhookeditor.py

@@ -0,0 +1,48 @@
+# Generated by Django 5.2.17 on 2026-10-17 12:42
+
+import uuid
+
+import django.db.models.deletion
+from django.conf import settings
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+    dependencies = [
+        ("webhooks", "0010_alter_webhook_disabled_at"),
+        migrations.swappable_dependency(settings.AUTH_USER_MODEL),
+    ]
+
+    operations = [
+        migrations.CreateModel(
+            name="WebhookEditor",
+            fields=[
+                (
+                    "id",
+                    models.UUIDField(
+                        default=uuid.uuid4, editable=False, primary_key=True, serialize=False
+                    ),
+                ),
+                ("set_at", models.DateTimeField(auto_now=True)),
+                (
+                    "user",
+                    models.ForeignKey(
+                        on_delete=django.db.models.deletion.CASCADE, to=settings.AUTH_USER_MODEL
+                    ),
+                ),
+                (
+                    "webhook",
+                    models.ForeignKey(
+                        on_delete=django.db.models.deletion.CASCADE,
+                        related_name="editors",
+                        to="webhooks.webhook",
+                    ),
+                ),
+            ],
+            options={
+                "constraints": [
+                    models.UniqueConstraint(fields=("webhook", "user"), name="uniq_webhook_editor")
+                ],
+            },
+        ),
+    ]

trueppm_api/apps/webhooks/migrations/0012_alter_webhook_disabled_at.py

@@ -0,0 +1,21 @@
+# Generated by Django 5.2.17 on 2026-10-19 14:51
+
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+    dependencies = [
+        ("webhooks", "0011_webhookeditor"),
+    ]
+
+    operations = [
+        migrations.AlterField(
+            model_name="webhook",
+            name="disabled_at",
+            field=models.DateTimeField(
+                blank=True,
+                help_text="When the automatic failure guard, or a credential-revocation sweep (password reset, off-boarding, or revoke_api_tokens --user/--all-personal/--all), deactivated this subscription. Null when it is active, or when an admin deactivated it by hand.",
+                null=True,
+            ),
+        ),
+    ]

trueppm_api/apps/webhooks/models.py

@@ -0,0 +1,437 @@
+"""Models for outbound webhook subscriptions and delivery tracking."""
+
+from __future__ import annotations
+
+import uuid
+from typing import Any
+
+from django.conf import settings
+from django.contrib.postgres.fields import ArrayField
+from django.db import models, transaction
+from django.utils import timezone
+
+from trueppm_api.apps.integrations.encryption import decrypt_secret, encrypt_secret
+
+
+class WebhookEventType(models.TextChoices):
+    TASK_CREATED = "task.created", "Task Created"
+    TASK_UPDATED = "task.updated", "Task Updated"
+    TASK_DELETED = "task.deleted", "Task Deleted"
+    DEPENDENCY_CREATED = "dependency.created", "Dependency Created"
+    DEPENDENCY_DELETED = "dependency.deleted", "Dependency Deleted"
+    SCHEDULE_RECALCULATED = "schedule.recalculated", "Schedule Recalculated"
+    PROJECT_CREATED = "project.created", "Project Created"
+    # Four new task events added in #638 (ADR-0083). task.due_date_changed
+    # currently fires on planned_start changes — #690 rebinds it to a dedicated
+    # planned_finish deadline field.
+    TASK_ASSIGNED = "task.assigned", "Task Assigned"
+    TASK_ASSIGNEE_CHANGED = "task.assignee_changed", "Task Assignee Changed"
+    TASK_MENTIONED = "task.mentioned", "Task Mentioned"
+    TASK_DUE_DATE_CHANGED = "task.due_date_changed", "Task Due Date Changed"
+    # Agile trio added in #1073 (ADR-0147). First-party domain events — they make
+    # the sprint-sovereignty story (ADR-0102/0104) observable to external tooling.
+    # sprint.closed's completion snapshot is velocity and is privacy-gated in its
+    # payload builder per ADR-0104 (see _sprint_closed_webhook_payload).
+    SPRINT_ACTIVATED = "sprint.activated", "Sprint Activated"
+    SPRINT_CLOSED = "sprint.closed", "Sprint Closed"
+    SPRINT_SCOPE_CHANGED = "sprint.scope_changed", "Sprint Scope Changed"
+    # Risk / baseline / comment domain events added in #1082 (ADR-0206). First-party
+    # domain events that extend the catalog beyond agile so external reporting and
+    # alerting tooling can observe the risk register, baseline captures, and the
+    # comment thread. risk.escalated fires when computed severity (probability ×
+    # impact) increases; risk.closed on the transition into CLOSED. comment.created
+    # carries no comment body (privacy-conservative) and is distinct from
+    # task.mentioned, which fires only when a comment mentions someone.
+    RISK_OPENED = "risk.opened", "Risk Opened"
+    RISK_ESCALATED = "risk.escalated", "Risk Escalated"
+    RISK_CLOSED = "risk.closed", "Risk Closed"
+    BASELINE_CAPTURED = "baseline.captured", "Baseline Captured"
+    COMMENT_CREATED = "comment.created", "Comment Created"
+
+
+ALL_WEBHOOK_EVENTS = [e.value for e in WebhookEventType]
+
+# Hard cap on the number of OSS webhook event types (ADR-0083, raised 11→14 by
+# ADR-0147 for the agile trio, then 14→19 by ADR-0206 for the risk/baseline/comment
+# domain events). Adding a 20th event requires its own ADR — this is the gate
+# against the per-customer event proliferation that is the explicit Enterprise
+# upsell. These are all first-party domain events, not custom/user-defined events,
+# so the upsell line is unaffected. ``test_event_type_cap`` fails loudly if
+# WebhookEventType drifts from this number.
+OSS_WEBHOOK_EVENT_CAP = 19
+
+# Reserved, non-domain event type used by the "Send test" action (#2884). It is
+# deliberately NOT a WebhookEventType member: no subscription can select it and
+# no domain mutation emits it, but a test ping is a real delivery — it renders
+# through the subscription's provider, allocates a sequence number, and carries
+# the ``_meta`` envelope like any other delivery, so a consumer doing in-body gap
+# detection does not see a phantom jump when an admin clicks Test.
+PING_EVENT_TYPE = "ping"
+
+# Consecutive terminal delivery failures after which a subscription is
+# automatically deactivated (#2884). Before this existed, a revoked receiver
+# answering 404/410 was retried forever with no state change: `is_active` was
+# only ever written by a human PATCH, so the queue and the receiver both burned
+# indefinitely. Five is one working day's worth of noise for a low-traffic
+# project and about a minute for a busy one — high enough that a brief receiver
+# outage does not trip it (a transient 5xx recovers within the retry chain and
+# resets the counter on the next success), low enough that a permanently broken
+# endpoint stops being retried.
+AUTO_DISABLE_CONSECUTIVE_FAILURES = 5
+
+
+class Webhook(models.Model):
+    """A registered outbound webhook subscription.
+
+    Polymorphically scoped to either a Project or a Program (ADR-0076).
+    A program-scoped webhook fires for events on any project within the
+    program; a project-scoped webhook fires only for that project. The DB
+    constraint enforces XOR — exactly one of project/program is set.
+    """
+
+    id = models.UUIDField(primary_key=True, default=uuid.uuid4, editable=False)
+    project = models.ForeignKey(
+        "projects.Project",
+        on_delete=models.CASCADE,
+        related_name="webhooks",
+        null=True,
+        blank=True,
+        help_text="Set when the webhook fires for events on a single project. "
+        "Exactly one of project/program is non-null (DB constraint).",
+    )
+    program = models.ForeignKey(
+        "projects.Program",
+        on_delete=models.CASCADE,
+        related_name="webhooks",
+        null=True,
+        blank=True,
+        help_text="Set when the webhook fires for events on any project within "
+        "this program. Exactly one of project/program is non-null (DB constraint).",
+    )
+    url = models.URLField(max_length=2048)
+    # Fernet ciphertext of the HMAC signing secret (#2885, ADR-0049 §3). This was
+    # the last plaintext secret in the product; every sibling secret
+    # (IntegrationCredential PAT, inbound git webhook secret, SSO client_secret,
+    # workspace SMTP password) already used this at-rest pattern, so a pg_dump or
+    # a read-only SQL finding yielded signing keys that let an attacker forge
+    # accepted deliveries at every registered receiver.
+    #
+    # Encrypted rather than hashed: signing needs the plaintext at delivery time
+    # (the same reason BoardAutomation.secret_ciphertext is encrypted and
+    # ApiToken's is hashed). Read and written through the ``secret`` property
+    # below, which keeps ``Webhook.objects.create(secret=...)`` and
+    # ``webhook.secret`` working — Django's ``Model.__init__`` routes an unknown
+    # kwarg to a same-named property with a setter.
+    secret_ciphertext = models.BinaryField(default=b"", blank=True, editable=False)
+    events = ArrayField(
+        models.CharField(max_length=30, choices=WebhookEventType.choices),
+        help_text="List of event types this webhook subscribes to.",
+    )
+    # Outgoing payload format (#638, ADR-0049/0083). NOT a TextChoices — validated
+    # at write time against OUTGOING_CHANNEL_PROVIDERS.keys() in the serializer, so
+    # Enterprise can register slack_app/teams without an OSS migration. Existing
+    # rows backfill to "generic" (the historical pass-through behavior).
+    format = models.CharField(max_length=32, default="generic")
+    is_active = models.BooleanField(default=True)
+    # Per-subscription delivery-health counters (#2884). Before these existed the
+    # only evidence of a failing endpoint was the per-webhook delivery log, which
+    # is Admin-only and purges terminal rows after TRUEPPM_WEBHOOK_RETENTION_DAYS
+    # (default 7) — so an outage older than a week left no trace anywhere.
+    #
+    # ``consecutive_failures`` counts *terminal* failures (a delivery that will
+    # never be attempted again), not individual attempts, and resets to 0 on the
+    # next success. ``disabled_at``/``disabled_reason`` are set by the automatic
+    # guard OR by ``revoke_personal_durable_grants`` (#4461) — never by a human
+    # PATCH — so the UI can distinguish "an admin paused this" from "TruePPM gave
+    # up on this" from "the registrant's credentials were revoked".
+    consecutive_failures = models.PositiveIntegerField(
+        default=0,
+        help_text="Terminal delivery failures since the last success. Resets to 0 "
+        "on any successful delivery.",
+    )
+    last_failure_at = models.DateTimeField(null=True, blank=True)
+    last_failure_reason = models.CharField(max_length=255, blank=True, default="")
+    disabled_at = models.DateTimeField(
+        null=True,
+        blank=True,
+        help_text="When the automatic failure guard, or a credential-revocation "
+        "sweep (password reset, off-boarding, or revoke_api_tokens --user/"
+        "--all-personal/--all), deactivated this subscription. Null when it is "
+        "active, or when an admin deactivated it by hand.",
+    )
+    disabled_reason = models.CharField(max_length=255, blank=True, default="")
+    # Per-subscription monotonic counter for outgoing deliveries (#664). Lives on
+    # the subscription, NOT derived from WebhookDelivery rows, because the
+    # retention purge (ADR-0081) deletes terminal deliveries — deriving the next
+    # value from the delivery table would reuse sequence numbers after a purge
+    # and silently corrupt the consumer-side gap-detection contract.
+    delivery_sequence = models.BigIntegerField(default=0, editable=False)
+    created_at = models.DateTimeField(auto_now_add=True)
+    created_by = models.ForeignKey(
+        settings.AUTH_USER_MODEL,
+        on_delete=models.SET_NULL,
+        null=True,
+        blank=True,
+    )
+
+    class Meta:
+        indexes = [
+            models.Index(fields=["project", "is_active"], name="webhook_project_active_idx"),
+            models.Index(fields=["program", "is_active"], name="webhook_program_active_idx"),
+        ]
+        constraints = [
+            models.CheckConstraint(
+                condition=(
+                    models.Q(project__isnull=False, program__isnull=True)
+                    | models.Q(project__isnull=True, program__isnull=False)
+                ),
+                name="webhook_scope_xor",
+            ),
+        ]
+
+    def __str__(self) -> str:
+        return f"Webhook {self.id} → {self.url}"
+
+    @property
+    def is_program_scoped(self) -> bool:
+        """True when this webhook fires for events on any project in a program."""
+        return self.program_id is not None
+
+    @property
+    def secret(self) -> str:
+        """The plaintext HMAC signing secret, decrypted from ``secret_ciphertext``.
+
+        Server-side only — it is never serialized to a client (the API echoes an
+        auto-generated secret exactly once at create time and a ``secret_set``
+        boolean thereafter). Returns ``""`` when no secret is stored, which the
+        delivery task treats as a configuration error rather than signing with an
+        empty key.
+        """
+        if not self.secret_ciphertext:
+            return ""
+        return decrypt_secret(self.secret_ciphertext)
+
+    @secret.setter
+    def secret(self, plaintext: str) -> None:
+        """Fernet-encrypt ``plaintext`` into ``secret_ciphertext`` (#2885).
+
+        A setter rather than an explicit ``set_secret()`` method so every existing
+        write path — ``Webhook.objects.create(secret=...)``, DRF's
+        ``setattr``-based ``ModelSerializer.update``, and fixtures — keeps working
+        against the encrypted column with no call-site change. Writing a new value
+        is the rotation path: the previous ciphertext is overwritten.
+        """
+        self.secret_ciphertext = encrypt_secret(plaintext) if plaintext else b""
+
+    @property
+    def secret_set(self) -> bool:
+        """Whether a signing secret is stored (the only thing the API exposes)."""
+        return bool(self.secret_ciphertext)
+
+    def record_delivery_success(self) -> None:
+        """Clear the failure counters after a delivery succeeds (#2884).
+
+        Guarded on a non-zero counter so the common case (a healthy webhook
+        delivering thousands of events) issues no UPDATE at all. Written with a
+        queryset update rather than ``save()`` because the caller holds a delivery
+        row, not a lock on the subscription, and two concurrent deliveries to the
+        same webhook would otherwise race on a stale in-memory copy.
+        """
+        if not (self.consecutive_failures or self.last_failure_at or self.disabled_at):
+            return
+        Webhook.objects.filter(pk=self.pk).update(
+            consecutive_failures=0,
+            last_failure_at=None,
+            last_failure_reason="",
+        )
+        self.consecutive_failures = 0
+        self.last_failure_at = None
+        self.last_failure_reason = ""
+
+    def record_delivery_failure(self, reason: str) -> bool:
+        """Count one *terminal* delivery failure; auto-disable past the threshold.
+
+        Called only when a delivery will never be attempted again — a permanent
+        client error, an exhausted retry chain, or an SSRF block. Attempts inside a
+        live retry chain must not be counted here, or a single event's five
+        attempts would trip the guard on their own.
+
+        The increment uses ``F()`` so concurrent fan-out to the same subscription
+        cannot lose a count, then re-reads the committed value to decide whether to
+        deactivate. Returns ``True`` when this call deactivated the subscription,
+        so the caller can log the transition once.
+        """
+        now = timezone.now()
+        Webhook.objects.filter(pk=self.pk).update(
+            consecutive_failures=models.F("consecutive_failures") + 1,
+            last_failure_at=now,
+            last_failure_reason=reason[:255],
+        )
+        failures: int = (
+            Webhook.objects.filter(pk=self.pk)
+            .values_list("consecutive_failures", flat=True)
+            .first()
+            or 0
+        )
+        self.consecutive_failures = failures
+        self.last_failure_at = now
+        self.last_failure_reason = reason[:255]
+
+        if failures < AUTO_DISABLE_CONSECUTIVE_FAILURES:
+            return False
+        # Only the first call across the threshold flips the flag, so a webhook
+        # already deactivated (by the guard or by an admin) is not re-stamped.
+        disabled_reason = (
+            f"Automatically deactivated after {failures} consecutive failed "
+            f"deliveries. Last failure: {reason}"
+        )[:255]
+        updated = Webhook.objects.filter(pk=self.pk, is_active=True).update(
+            is_active=False,
+            disabled_at=now,
+            disabled_reason=disabled_reason,
+        )
+        if updated:
+            self.is_active = False
+            self.disabled_at = now
+            self.disabled_reason = disabled_reason
+        return bool(updated)
+
+
+class WebhookEditor(models.Model):
+    """Every user who has ever set a webhook's `url`/`secret`, or re-enabled it
+    while disabled (#4461).
+
+    **Additive by design — never overwritten.** `revoke_personal_durable_grants`'s
+    sweep must deactivate a webhook for every account whose credential compromise
+    could have put the webhook's *current* URL/secret in place, not only the one
+    who most recently touched it. A single mutable "last modified by" field looked
+    like the obvious shape and was tried first, and it broke on the very next
+    edit: a project webhook's update has no registrant check, so any project Admin
+    may edit any project webhook (ADR-0076's creator-only rule is program-scoped
+    only, #4310). Given a hijacked session (Admin B) repoints `url` to an
+    attacker's host, a single mutable field fails two ways once a *different*,
+    legitimate admin (A) later touches the row at all:
+
+    - A's own later secret rotation overwrites the stamp to A — B's own password
+      reset/off-boarding no longer matches, and the row survives it.
+    - Even a PUT that only changes `events` carries the (unchanged, still evil)
+      `url` in its body — DRF's serializer treats a present-but-unchanged field
+      as "set" — so the stamp flips to A on a write that touched neither field in
+      substance.
+
+    A row here is therefore inserted once per (webhook, user) and never deleted
+    or reassigned to someone else; a later editor can only ADD their own row, not
+    remove this one. `set_at` is refreshed on every qualifying edit by the same
+    user (informational — "last confirmed", not "only"), via `update_or_create`.
+    The sweep matches `created_by=user OR user in webhook.editors` — both legs,
+    because `created_by` is the registrant even if they never edited the row at
+    all, and this table is editors, not registrants.
+
+    A row is also inserted when a user flips a disabled webhook's `is_active`
+    back to `True` (``WebhookViewSet.perform_update``), even with `url`/`secret`
+    untouched: a webhook that is disabled still carries whatever `url`/`secret`
+    it had, so re-enabling it restarts delivery to wherever it currently
+    points. A second hijacked session that does nothing but re-enable the row
+    must be recorded, or its own future containment would miss it despite
+    being the one that restarted the leak. *Disabling* is deliberately NOT
+    recorded — it only shrinks what is live, the opposite shape.
+
+    Mirrors the shape of ``TaskLabel``/``CommentReaction`` (plain through model,
+    UUID PK, ``unique(webhook, user)``) rather than a ``ManyToManyField`` so the
+    upsert (``update_or_create``) and the `set_at` timestamp have somewhere to
+    live.
+    """
+
+    id = models.UUIDField(primary_key=True, default=uuid.uuid4, editable=False)
+    webhook = models.ForeignKey(Webhook, on_delete=models.CASCADE, related_name="editors")
+    # CASCADE: a deleted user cannot be the subject of a future credential sweep
+    # anyway — unlike Webhook.created_by (SET_NULL), there is no "unattributed but
+    # still relevant" state to preserve here.
+    user = models.ForeignKey(settings.AUTH_USER_MODEL, on_delete=models.CASCADE)
+    set_at = models.DateTimeField(auto_now=True)
+
+    class Meta:
+        constraints = [
+            models.UniqueConstraint(fields=["webhook", "user"], name="uniq_webhook_editor"),
+        ]
+
+    def __str__(self) -> str:
+        return f"WebhookEditor({self.webhook_id}, {self.user_id})"
+
+
+def _next_delivery_sequence(webhook_id: uuid.UUID | str) -> int:
+    """Atomically allocate the next per-subscription delivery sequence number.
+
+    Locks the Webhook row with ``select_for_update`` and increments its
+    ``delivery_sequence`` counter inside an explicit transaction. The lock is
+    held until commit, so concurrent deliveries to the same subscription receive
+    strictly increasing, *contiguous* numbers — a gap at the consumer therefore
+    signals a genuinely lost event, which is the whole point of the gap-detection
+    contract (#664).
+
+    The explicit ``transaction.atomic()`` is required because ``dispatch_webhooks``
+    runs from a ``transaction.on_commit`` callback (autocommit context); without
+    the surrounding transaction the increment + read-back would race.
+    """
+    with transaction.atomic():
+        webhook = Webhook.objects.select_for_update().get(pk=webhook_id)
+        webhook.delivery_sequence += 1
+        webhook.save(update_fields=["delivery_sequence"])
+        return webhook.delivery_sequence
+
+
+class DeliveryStatus(models.TextChoices):
+    PENDING = "pending", "Pending"
+    SUCCESS = "success", "Success"
+    FAILED = "failed", "Failed"
+
+
+class WebhookDelivery(models.Model):
+    """Record of a single webhook delivery attempt (or series of retries)."""
+
+    id = models.UUIDField(primary_key=True, default=uuid.uuid4, editable=False)
+    webhook = models.ForeignKey(
+        Webhook,
+        on_delete=models.CASCADE,
+        related_name="deliveries",
+    )
+    # ``choices`` documents the subscribable domain events; it is validation-only
+    # (no DB constraint), which is what lets the reserved PING_EVENT_TYPE — not a
+    # WebhookEventType member because nothing can subscribe to it — be recorded
+    # here as a real delivery.
+    event_type = models.CharField(max_length=30, choices=WebhookEventType.choices)
+    payload = models.JSONField()
+    # Monotonic per-subscription sequence, allocated once on INSERT and never
+    # changed across retries (the same row keeps its number). Sent to the
+    # consumer in the X-TruePPM-Webhook-Sequence header so it can detect gaps
+    # and reorder out-of-order events. The default of 0 is only a placeholder
+    # for the add-column migration; every row created through save() is assigned
+    # a real value >= 1 via _next_delivery_sequence().
+    sequence_number = models.BigIntegerField(default=0, editable=False)
+    status = models.CharField(
+        max_length=10,
+        choices=DeliveryStatus.choices,
+        default=DeliveryStatus.PENDING,
+    )
+    response_status = models.SmallIntegerField(null=True, blank=True)
+    attempt_count = models.SmallIntegerField(default=0)
+    created_at = models.DateTimeField(auto_now_add=True)
+    completed_at = models.DateTimeField(null=True, blank=True)
+
+    class Meta:
+        indexes = [
+            models.Index(fields=["webhook", "created_at"], name="delivery_webhook_created_idx"),
+            models.Index(fields=["status", "created_at"], name="delivery_status_created_idx"),
+        ]
+        ordering = ["-created_at"]
+
+    def __str__(self) -> str:
+        return f"Delivery {self.id} [{self.status}]"
+
+    def save(self, *args: Any, **kwargs: Any) -> None:
+        # Allocate the per-subscription sequence on INSERT only, so the number is
+        # stable across the Celery retry chain (deliver_webhook re-saves the same
+        # row on every attempt and must not re-number it).
+        if self._state.adding and not self.sequence_number:
+            self.sequence_number = _next_delivery_sequence(self.webhook_id)
+        super().save(*args, **kwargs)