Webhook events reference

All webhook deliveries share the same envelope:

{
  "event": "<event_code>",
  "created_at": "2026-06-08T14:23:00.000Z",
  "data": { ... }
}

The data object is event-specific and documented below.

Signature verification: see Webhooks concepts.

---

invoice.created

Fired when an invoice is generated — either at period close (arrears charges) or at subscription start (immediate charges), or when an add-on is applied.

{
  "event": "invoice.created",
  "created_at": "2026-07-01T00:01:00.000Z",
  "data": {
    "invoice": {
      "id": "uuid",
      "number": "INV-2026-0042",
      "status": "outstanding",
      "payment_status": "pending",
      "invoice_type": "subscription",
      "currency": "USD",
      "subtotal_cents": 847,
      "total_cents": 847,
      "issuing_date": "2026-07-01",
      "due_date": "2026-07-15",
      "period_start": "2026-06-01",
      "period_end": "2026-06-30",
      "fees": [
        {
          "id": "uuid",
          "fee_type": "charge",
          "billable_metric_code": "mail_out",
          "units": "640",
          "amount_cents": 128,
          "amount_currency": "USD",
          "properties": { "amount": "0.0002" }
        }
      ]
    },
    "customer": {
      "id": "uuid",
      "external_id": "emailfs_account_abc123",
      "name": "Ali Yilmaz",
      "email": "ali@acme.com"
    },
    "subscription": {
      "id": "uuid",
      "external_id": "emailfs_sub_abc123",
      "plan_code": "emailfs-team"
    }
  }
}

What to do: initiate payment collection. Record the payment with POST /v1/payments when confirmed.

---

payment.succeeded

Fired when a payment is recorded against an invoice via POST /v1/payments.

{
  "event": "payment.succeeded",
  "created_at": "2026-07-05T14:22:00.000Z",
  "data": {
    "payment": {
      "id": "uuid",
      "invoice_id": "uuid",
      "amount_cents": 847,
      "currency": "USD",
      "provider": "stripe",
      "provider_payment_id": "pi_3abc123",
      "paid_at": "2026-07-05T14:22:00.000Z"
    },
    "invoice": {
      "id": "uuid",
      "number": "INV-2026-0042",
      "status": "succeeded",
      "payment_status": "succeeded",
      "total_cents": 847,
      "currency": "USD"
    },
    "customer": {
      "id": "uuid",
      "external_id": "emailfs_account_abc123"
    }
  }
}

What to do: update your system's payment records; resume any suspended services.

---

subscription.period_renewed

Fired when a billing period closes and a new one begins.

{
  "event": "subscription.period_renewed",
  "created_at": "2026-07-01T00:01:00.000Z",
  "data": {
    "subscription": {
      "id": "uuid",
      "external_id": "emailfs_sub_abc123",
      "plan_code": "emailfs-starter",
      "status": "active",
      "current_period_start": "2026-07-01T00:00:00.000Z",
      "current_period_end": "2026-07-31T23:59:59.000Z"
    },
    "customer": {
      "id": "uuid",
      "external_id": "emailfs_account_abc123"
    },
    "previous_period": {
      "start": "2026-06-01T00:00:00.000Z",
      "end": "2026-06-30T23:59:59.000Z"
    }
  }
}

What to do: reset any internal usage counters you maintain; send period summary emails if desired.

---

addon.applied

Fired when an add-on is applied to a customer via POST /v1/addons/:id/apply.

{
  "event": "addon.applied",
  "created_at": "2026-06-15T10:30:00.000Z",
  "data": {
    "applied_add_on": {
      "id": "uuid",
      "add_on_code": "domain-transfer-com",
      "add_on_name": ".com Transfer",
      "amount_cents": 1296,
      "currency": "USD",
      "applied_at": "2026-06-15T10:30:00.000Z"
    },
    "invoice": {
      "id": "uuid",
      "number": "INV-2026-0043",
      "total_cents": 1296,
      "currency": "USD",
      "invoice_type": "addon"
    },
    "customer": {
      "id": "uuid",
      "external_id": "hostco-account-789"
    }
  }
}

What to do: initiate payment collection for the add-on invoice.

---

invoice.payment_overdue_reminder_1

Fired by the dunning job when an invoice is 3 days past due_date (configurable in driptab.yaml).

{
  "event": "invoice.payment_overdue_reminder_1",
  "created_at": "2026-07-18T00:00:00.000Z",
  "data": {
    "invoice": {
      "id": "uuid",
      "number": "INV-2026-0042",
      "status": "overdue",
      "total_cents": 847,
      "currency": "USD",
      "issuing_date": "2026-07-01",
      "due_date": "2026-07-15"
    },
    "customer": {
      "id": "uuid",
      "external_id": "emailfs_account_abc123",
      "name": "Ali Yilmaz",
      "email": "ali@acme.com"
    },
    "days_overdue": 3
  }
}

What to do: send a payment reminder email.

---

invoice.payment_overdue_reminder_2

Same shape as invoice.payment_overdue_reminder_1, fired at 7 days past due.

What to do: send a second, more urgent reminder. Optionally retry the payment method.

---

subscription.suspend_requested

Fired at the configured dunning threshold (default: 14 days past due). Driptab is requesting that your system suspend the subscription.

{
  "event": "subscription.suspend_requested",
  "created_at": "2026-07-29T00:00:00.000Z",
  "data": {
    "subscription": {
      "id": "uuid",
      "external_id": "emailfs_sub_abc123",
      "plan_code": "emailfs-starter",
      "status": "active"
    },
    "customer": {
      "id": "uuid",
      "external_id": "emailfs_account_abc123",
      "email": "ali@acme.com"
    },
    "overdue_invoice": {
      "id": "uuid",
      "number": "INV-2026-0042",
      "total_cents": 847,
      "days_overdue": 14
    }
  }
}

What to do:

1. Disable service access in your system.
2. Call POST /v1/subscriptions/:id/suspend to update the subscription status in Driptab.
3. Send a suspension notification to the customer.

---

subscription.terminate_requested

Fired at the configured dunning threshold (default: 30 days past due). Driptab is requesting permanent termination.

Same shape as subscription.suspend_requested, with days_overdue: 30.

What to do:

1. Permanently terminate service access.
2. Call POST /v1/subscriptions/:id/terminate.
3. Send a termination notice to the customer.

---

Delivery guarantees

Webhooks are delivered at-least-once. Your endpoint should be idempotent — check whether you have already processed an event before taking action. The event + data.invoice.id (or equivalent resource ID) combination can serve as an idempotency key.

Driptab retries failed deliveries (non-2xx or timeout) with exponential backoff. The first retry is approximately 5 minutes after the initial failure.