subscriber.activated - Settlx

When it fires

After the subscriber’s first invoice is paid and the on-chain payment is confirmed. The subscriber’s status transitions from pending to active. This also fires when a previously past_due subscriber pays and their subscription is renewed.

What to do

This is the event to act on. Provision access to your product here.

Activate the customer’s account
Unlock the tier they subscribed to
Send a “you’re all set” confirmation email
Record the subscription start in your database

subscriber.activated fires both on the first payment (from pending) and on renewal payments (from past_due). Handle both cases the same way — ensure access is granted/maintained.

Payload

{
  "event": "subscriber.activated",
  "subscriberId": "9f1e2d3c-4b5a-6789-abcd-ef0123456789",
  "merchantId": "f9e8d7c6-b5a4-3210-9876-543210fedcba",
  "planId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "email": "customer@example.com",
  "status": "active",
  "currentPeriodEnd": "2026-05-19T00:00:00.000Z",
  "timestamp": "2026-04-19T10:45:00.000Z"
}

Field	Type	Description
`event`	string	Always `subscriber.activated`
`subscriberId`	string	UUID of the subscriber record
`merchantId`	string	Your merchant account UUID
`planId`	string	UUID of the plan
`email`	string	Subscriber email address
`status`	string	Always `active`
`currentPeriodEnd`	string	ISO 8601 — end of the newly activated billing period
`timestamp`	string	ISO 8601 — when the event was generated

Handler example

Node.js

app.post('/webhooks/settlx', express.raw({ type: 'application/json' }), async (req, res) => {
  verifySignature(req); // see Webhook Integration for verification code

  const event = JSON.parse(req.body);

  if (event.event === 'subscriber.activated') {
    const { subscriberId, email, planId, currentPeriodEnd } = event;

    // Use subscriberId for idempotency — this event fires on every renewal
    const alreadyActive = await db.subscriptions.isActive(subscriberId, currentPeriodEnd);
    if (alreadyActive) {
      return res.status(200).json({ received: true });
    }

    // Provision or renew access
    await db.subscriptions.update(subscriberId, {
      status: 'active',
      accessUntil: currentPeriodEnd,
    });

    await grantAccess(email, planId);

    await sendEmail(email, 'subscription-active', {
      renewsAt: currentPeriodEnd,
    });
  }

  res.status(200).json({ received: true });
});

subscriber.enrolled — Enrollment created, awaiting first payment.
subscriber.past_due — New cycle started, renewal invoice issued.
subscriber.expired — Renewal not received before grace period ended.