Skip to main content

Webhook Management

This guide explains how to receive and verify Pulse Billing webhook notifications. Webhooks let your application react in real time to orders, subscriptions, renewals, and cancellations.

Overview​

The Pulse Billing webhook system provides a secure way to:

  • Receive real-time notifications when customers purchase or renew
  • Correlate renewals and cancellations to the same customer and order
  • Verify that requests genuinely come from Pulse (HMAC signatures)
  • Recover from outages with automatic retries and manual replay

Prefer webhook signatures over IP allowlisting. Pulse does not publish a static outbound IP range.

Configure Webhooks in Settings​

Access webhook configuration​

  1. Open Settings in Pulse Billing
  2. Select the Webhooks tab
  3. Click + Add Webhook to create an endpoint

Create a webhook endpoint​

FieldDescription
Webhook NameDescriptive label (e.g. production_orders)
Webhook URLFull HTTPS URL of your receiver
Signing secretGenerated automatically as whsec_… — store it securely and use it to verify Pulse-Signature

Manage existing webhooks​

  • Copy or regenerate the signing secret from the webhook table (regenerating invalidates the previous secret)
  • Delete endpoints you no longer need
  • Review Failed deliveries and use Replay to re-send exhausted events

Webhook Delivery​

Request Format​

POST {your-webhook-url}
Content-Type: application/json
Pulse-Signature: t={unix_timestamp},v1={hmac_sha256_hex}
Pulse-Event-Id: evt_{id}

Request Headers​

HeaderTypeRequiredDescription
Content-TypestringYesAlways application/json
Pulse-SignaturestringYest={unix},v1={hex} — HMAC-SHA256 of {t}.{raw_body} using your signing secret
Pulse-Event-IdstringYesStable delivery id for idempotent handling (at-least-once delivery)

Endpoint Requirements​

RequirementValue
HTTP methodPOST
Content typeapplication/json
Response timeUnder 30 seconds
Success statusAny 2xx
IdempotencyDeduplicate on Pulse-Event-Id
SignatureVerify Pulse-Signature before processing

Payload Format​

{
"ProductId": 123,
"PricePlanId": 17,
"OrderItemId": 456,
"OrderId": 1001,
"CustomerId": 42,
"TransactionId": 789,
"Amount": 10.00,
"Currency": "usd",
"Discount": 0.00,
"Quantity": 1,
"EventType": "NewOrder",
"ContactPerson": {
"FirstName": "John",
"LastName": "Doe",
"Email": "[email protected]"
},
"Address": {
"Line1": "123 Main Street",
"Line2": "Apt 4B",
"City": "New York",
"State": "NY",
"PostalCode": "10001",
"Country": "United States"
}
}

Subscription events (NewSubscription, SubscriptionRenewal, SubscriptionCancellation) also include NextBillingDate when the payment provider reports it:

{
"EventType": "NewSubscription",
"NextBillingDate": "2026-11-01T00:00:00Z",
"Amount": 29.00,
"Currency": "usd"
}

Parameters​

ParameterTypeRequiredDescription
ProductIdintegerYesProduct that was purchased
PricePlanIdintegerYesPricing plan (SKU) the customer purchased
OrderItemIdintegerYesOrder line-item ID
OrderIdintegerYesParent product order ID — use to correlate renewals and cancellations with the original order
CustomerIdintegerYesStable licensee (customer) ID — does not change if the customer updates their email
TransactionIdintegerYesPayment / activity transaction ID
AmountnumberYesAmount charged for this transaction
CurrencystringYesISO currency code in lowercase (e.g. usd, eur)
DiscountnumberYesDiscount applied (0 if none)
QuantityintegerYesQuantity purchased for this order line item
EventTypestringYesEvent that triggered the webhook
NextBillingDatestring (ISO-8601 UTC)NoNext charge date. Sent on NewSubscription and SubscriptionRenewal. On SubscriptionCancellation this is when the current period ends (no further charges). Omitted for one-time orders, refunds, and disputes.
ContactPersonobjectYesCustomer contact information
ContactPerson.FirstNamestringYesCustomer's first name
ContactPerson.LastNamestringYesCustomer's last name
ContactPerson.EmailstringYesCustomer's email address
AddressobjectYesBilling address
Address.Line1stringYesPrimary address line
Address.Line2stringNoSecondary address line
Address.CitystringYesCity
Address.StatestringYesState or province
Address.PostalCodestringYesPostal / ZIP code
Address.CountrystringYesFull country name

EventType Values​

EventTypeDescriptionTriggered When
NewOrderOne-time purchase completedCustomer completes a one-time purchase
NewSubscriptionSubscription startedCustomer starts their first subscription period
SubscriptionRenewalSubscription renewedExisting subscription renews for another period
SubscriptionCancellationSubscription terminatedSubscription access ends
RefundPayment refundedA refund is issued against a payment
DisputeCreatedChargeback / dispute openedA payment dispute is created
DisputeWonDispute resolved in merchant favorDispute is won
DisputeLostDispute resolved in customer favorDispute is lost (funds reversed)
sms.receivedInbound customer textA customer texts your sending number
sms.deliveredOutbound SMS deliveredThe carrier confirms delivery
sms.failedOutbound SMS failedThe send failed or was undelivered
sms.opted_inSMS consent recordedCheckout, buyer portal, START, or a vendor-recorded opt-in
sms.opted_outSMS consent withdrawnSTOP, buyer portal, or a vendor-recorded opt-out

SMS events are sent only when Settings → SMS → Send SMS webhook events is on (the default). They use the same Pulse-Signature and Pulse-Event-Id headers as order events, but a different JSON body — there is often no order or SKU on an inbound reply.

SMS events​

{
"EventType": "sms.received",
"ConversationId": 42,
"MessageId": 108,
"Direction": "Inbound",
"Status": "Received",
"FromNumber": "+14155552671",
"ToNumber": "+14155550100",
"Body": "Thanks, got the license key.",
"NumSegments": 1,
"NumMedia": 0,
"CustomerId": 17,
"ContactPerson": null,
"ProviderMessageSid": "SMxxxxxxxx",
"ProviderErrorCode": null,
"ErrorMessage": null,
"OccurredAt": "2026-09-28T12:04:11Z"
}
ParameterTypeDescription
EventTypestringsms.received, sms.delivered, sms.failed, sms.opted_in, or sms.opted_out
ConversationIdintegerInbox thread id
MessageIdintegerMessage id
DirectionstringInbound or Outbound
StatusstringDelivery or receive status
FromNumberstringE.164 sender
ToNumberstringE.164 recipient
BodystringMessage text
NumSegmentsintegerBilled segments for this message
NumMediaintegerAttachment count
CustomerIdinteger or nullLicensee id when Pulse can match the number
ProviderMessageSidstring or nullCarrier message id
ProviderErrorCodeinteger or nullCarrier error on failures
ErrorMessagestring or nullFailure detail
OccurredAtstringUTC timestamp

Ignore unknown EventType values (including any sms.* name you do not handle). See Text Messaging.

Verify the Signature​

Before processing the body:

  1. Parse t and v1 from the Pulse-Signature header
  2. Reject the request if t is older than ~5 minutes (replay protection)
  3. Compute HMAC-SHA256 of "{t}.{rawRequestBody}" with your signing secret (UTF-8)
  4. Compare the lowercase hex digest to v1 using a constant-time comparison
  5. Only then parse and handle the JSON body

Signature Verification Examples​

const crypto = require('crypto');

function verifyPulseSignature(signingSecret, rawBody, signatureHeader, toleranceSeconds = 300) {
const parts = Object.fromEntries(
signatureHeader.split(',').map((p) => p.trim().split('='))
);
const timestamp = parts.t;
const signature = parts.v1;
if (!timestamp || !signature) {
return false;
}

const age = Math.abs(Math.floor(Date.now() / 1000) - Number(timestamp));
if (age > toleranceSeconds) {
return false;
}

const expected = crypto
.createHmac('sha256', signingSecret)
.update(`${timestamp}.${rawBody}`)
.digest('hex');

const expectedBuf = Buffer.from(expected, 'utf8');
const signatureBuf = Buffer.from(signature, 'utf8');
if (expectedBuf.length !== signatureBuf.length) {
return false;
}

return crypto.timingSafeEqual(expectedBuf, signatureBuf);
}

// Express example — use raw body for verification
app.post('/webhooks/pulse', express.raw({ type: 'application/json' }), (req, res) => {
const rawBody = req.body.toString('utf8');
const signatureHeader = req.get('Pulse-Signature');
const eventId = req.get('Pulse-Event-Id');

if (!verifyPulseSignature(process.env.PULSE_WEBHOOK_SECRET, rawBody, signatureHeader)) {
return res.status(401).send('Invalid signature');
}

if (alreadyProcessed(eventId)) {
return res.status(200).json({ status: 'duplicate' });
}

const event = JSON.parse(rawBody);
handlePulseEvent(event);
markProcessed(eventId);
return res.status(200).json({ status: 'success' });
});

Integration Examples​

Handle events by EventType, and use CustomerId / OrderId to keep your records in sync when email addresses change.

function handlePulseEvent(event) {
const { EventType, CustomerId, OrderId, OrderItemId, ContactPerson } = event;

switch (EventType) {
case 'NewOrder':
case 'NewSubscription':
upsertCustomer(CustomerId, ContactPerson);
createOrder(CustomerId, OrderId, OrderItemId, event);
break;

case 'SubscriptionRenewal':
// Same CustomerId / OrderId as the original subscription
recordRenewal(CustomerId, OrderId, event);
break;

case 'SubscriptionCancellation':
revokeAccess(CustomerId, OrderId);
break;

case 'Refund':
case 'DisputeLost':
recordCredit(CustomerId, OrderId, event);
break;

case 'DisputeCreated':
recordDisputeOpened(CustomerId, OrderId, event);
break;

case 'DisputeWon':
recordDisputeWon(CustomerId, OrderId, event);
break;

default:
console.warn('Unhandled event type:', EventType);
}
}

Retries and Reconciliation​

If your endpoint is unreachable or returns a non-2xx status:

  1. Pulse retries the first three failures 30 seconds apart
  2. Further attempts use exponential backoff (2m → 5m → 15m → 1h → 3h → 6h → 12h…) for up to 3 days from the first attempt
  3. A 410 Gone response marks the delivery as permanently failed (no further automatic retries)
  4. Exhausted deliveries appear under Settings → Webhooks → Failed deliveries
  5. Use Replay to queue a failed delivery again (same payload and Pulse-Event-Id)

Deliveries are persisted in Pulse; automatic retries survive application restarts.

Response Requirements​

Success Response (2xx)​

Any HTTP status in the 200–299 range acknowledges the delivery.

{
"status": "success"
}

Error Response (4xx / 5xx)​

Non-success responses are retried according to the schedule above (except 410 Gone).

{
"status": "error",
"message": "Error processing webhook"
}

Error Handling​

Common Error Scenarios​

ScenarioHTTP status from your endpointPulse behaviorAction
Accepted2xxMarked deliveredNone
Temporary failure5xx / timeoutRetried with backoffFix endpoint; check Failed deliveries if exhausted
Validation error400Retried with backoffFix payload handling
Unauthorized401Retried with backoffCheck signature verification and signing secret
Not found404Retried with backoffVerify webhook URL in Settings
Endpoint retired410Permanently failedUpdate or delete the webhook; optional Replay after fix
Duplicate delivery2xx after idempotent no-opMarked deliveredDeduplicate on Pulse-Event-Id

Best Practices​

  • Verify signatures on every request before parsing JSON
  • Use the raw request body for HMAC (do not re-serialize parsed JSON)
  • Treat deliveries as at-least-once — store Pulse-Event-Id and ignore duplicates
  • Key records by CustomerId and OrderId, not email alone
  • Return 2xx quickly — do heavy work asynchronously after acknowledging
  • Return 410 only when the endpoint should stop receiving retries

Ready to integrate webhooks? Set up endpoints in Settings → Webhooks to receive real-time notifications about customer orders, subscriptions, and payments.