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
- Open Settings in Pulse Billing
- Select the Webhooks tab
- Click + Add Webhook to create an endpoint
Create a webhook endpoint
| Field | Description |
|---|---|
| Webhook Name | Descriptive label (e.g. production_orders) |
| Webhook URL | Full HTTPS URL of your receiver |
| Signing secret | Generated 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
| Header | Type | Required | Description |
|---|---|---|---|
Content-Type | string | Yes | Always application/json |
Pulse-Signature | string | Yes | t={unix},v1={hex} — HMAC-SHA256 of {t}.{raw_body} using your signing secret |
Pulse-Event-Id | string | Yes | Stable delivery id for idempotent handling (at-least-once delivery) |
Endpoint Requirements
| Requirement | Value |
|---|---|
| HTTP method | POST |
| Content type | application/json |
| Response time | Under 30 seconds |
| Success status | Any 2xx |
| Idempotency | Deduplicate on Pulse-Event-Id |
| Signature | Verify 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
| Parameter | Type | Required | Description |
|---|---|---|---|
ProductId | integer | Yes | Product that was purchased |
PricePlanId | integer | Yes | Pricing plan (SKU) the customer purchased |
OrderItemId | integer | Yes | Order line-item ID |
OrderId | integer | Yes | Parent product order ID — use to correlate renewals and cancellations with the original order |
CustomerId | integer | Yes | Stable licensee (customer) ID — does not change if the customer updates their email |
TransactionId | integer | Yes | Payment / activity transaction ID |
Amount | number | Yes | Amount charged for this transaction |
Currency | string | Yes | ISO currency code in lowercase (e.g. usd, eur) |
Discount | number | Yes | Discount applied (0 if none) |
Quantity | integer | Yes | Quantity purchased for this order line item |
EventType | string | Yes | Event that triggered the webhook |
NextBillingDate | string (ISO-8601 UTC) | No | Next 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. |
ContactPerson | object | Yes | Customer contact information |
ContactPerson.FirstName | string | Yes | Customer's first name |
ContactPerson.LastName | string | Yes | Customer's last name |
ContactPerson.Email | string | Yes | Customer's email address |
Address | object | Yes | Billing address |
Address.Line1 | string | Yes | Primary address line |
Address.Line2 | string | No | Secondary address line |
Address.City | string | Yes | City |
Address.State | string | Yes | State or province |
Address.PostalCode | string | Yes | Postal / ZIP code |
Address.Country | string | Yes | Full country name |
EventType Values
| EventType | Description | Triggered When |
|---|---|---|
NewOrder | One-time purchase completed | Customer completes a one-time purchase |
NewSubscription | Subscription started | Customer starts their first subscription period |
SubscriptionRenewal | Subscription renewed | Existing subscription renews for another period |
SubscriptionCancellation | Subscription terminated | Subscription access ends |
Refund | Payment refunded | A refund is issued against a payment |
DisputeCreated | Chargeback / dispute opened | A payment dispute is created |
DisputeWon | Dispute resolved in merchant favor | Dispute is won |
DisputeLost | Dispute resolved in customer favor | Dispute is lost (funds reversed) |
sms.received | Inbound customer text | A customer texts your sending number |
sms.delivered | Outbound SMS delivered | The carrier confirms delivery |
sms.failed | Outbound SMS failed | The send failed or was undelivered |
sms.opted_in | SMS consent recorded | Checkout, buyer portal, START, or a vendor-recorded opt-in |
sms.opted_out | SMS consent withdrawn | STOP, 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"
}
| Parameter | Type | Description |
|---|---|---|
EventType | string | sms.received, sms.delivered, sms.failed, sms.opted_in, or sms.opted_out |
ConversationId | integer | Inbox thread id |
MessageId | integer | Message id |
Direction | string | Inbound or Outbound |
Status | string | Delivery or receive status |
FromNumber | string | E.164 sender |
ToNumber | string | E.164 recipient |
Body | string | Message text |
NumSegments | integer | Billed segments for this message |
NumMedia | integer | Attachment count |
CustomerId | integer or null | Licensee id when Pulse can match the number |
ProviderMessageSid | string or null | Carrier message id |
ProviderErrorCode | integer or null | Carrier error on failures |
ErrorMessage | string or null | Failure detail |
OccurredAt | string | UTC timestamp |
Ignore unknown EventType values (including any sms.* name you do not handle). See Text Messaging.
Verify the Signature
Before processing the body:
- Parse
tandv1from thePulse-Signatureheader - Reject the request if
tis older than ~5 minutes (replay protection) - Compute
HMAC-SHA256of"{t}.{rawRequestBody}"with your signing secret (UTF-8) - Compare the lowercase hex digest to
v1using a constant-time comparison - Only then parse and handle the JSON body
Signature Verification Examples
- JavaScript
- Python
- C#
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' });
});
import hashlib
import hmac
import json
import time
from flask import Flask, request
app = Flask(__name__)
SIGNING_SECRET = 'whsec_YOUR_SECRET'
def verify_pulse_signature(signing_secret: str, raw_body: bytes, signature_header: str, tolerance_seconds: int = 300) -> bool:
parts = dict(item.split('=', 1) for item in signature_header.split(',') if '=' in item)
timestamp = parts.get('t')
signature = parts.get('v1')
if not timestamp or not signature:
return False
if abs(int(time.time()) - int(timestamp)) > tolerance_seconds:
return False
payload = f'{timestamp}.{raw_body.decode("utf-8")}'.encode('utf-8')
expected = hmac.new(signing_secret.encode('utf-8'), payload, hashlib.sha256).hexdigest()
return hmac.compare_digest(expected, signature)
@app.post('/webhooks/pulse')
def pulse_webhook():
raw_body = request.get_data()
signature_header = request.headers.get('Pulse-Signature', '')
event_id = request.headers.get('Pulse-Event-Id')
if not verify_pulse_signature(SIGNING_SECRET, raw_body, signature_header):
return {'error': 'Invalid signature'}, 401
if already_processed(event_id):
return {'status': 'duplicate'}, 200
event = json.loads(raw_body)
handle_pulse_event(event)
mark_processed(event_id)
return {'status': 'success'}, 200
using System.Security.Cryptography;
using System.Text;
public static class PulseWebhookVerifier
{
public static bool VerifySignature(
string signingSecret,
string rawBody,
string signatureHeader,
int toleranceSeconds = 300)
{
var parts = signatureHeader
.Split(',', StringSplitOptions.RemoveEmptyEntries | StringSplitOptions.TrimEntries)
.Select(p => p.Split('=', 2))
.Where(p => p.Length == 2)
.ToDictionary(p => p[0], p => p[1]);
if (!parts.TryGetValue("t", out var timestamp) ||
!parts.TryGetValue("v1", out var signature))
{
return false;
}
var unixNow = DateTimeOffset.UtcNow.ToUnixTimeSeconds();
if (Math.Abs(unixNow - long.Parse(timestamp)) > toleranceSeconds)
{
return false;
}
var payload = Encoding.UTF8.GetBytes($"{timestamp}.{rawBody}");
var key = Encoding.UTF8.GetBytes(signingSecret);
var hash = HMACSHA256.HashData(key, payload);
var expected = Convert.ToHexString(hash).ToLowerInvariant();
return CryptographicOperations.FixedTimeEquals(
Encoding.UTF8.GetBytes(expected),
Encoding.UTF8.GetBytes(signature));
}
}
// ASP.NET Core minimal API example
app.MapPost("/webhooks/pulse", async (HttpRequest request) =>
{
using var reader = new StreamReader(request.Body, Encoding.UTF8);
var rawBody = await reader.ReadToEndAsync();
var signatureHeader = request.Headers["Pulse-Signature"].ToString();
var eventId = request.Headers["Pulse-Event-Id"].ToString();
if (!PulseWebhookVerifier.VerifySignature(
Environment.GetEnvironmentVariable("PULSE_WEBHOOK_SECRET")!,
rawBody,
signatureHeader))
{
return Results.Unauthorized();
}
if (AlreadyProcessed(eventId))
{
return Results.Ok(new { status = "duplicate" });
}
var eventData = JsonSerializer.Deserialize<PulseWebhookEvent>(rawBody);
HandlePulseEvent(eventData);
MarkProcessed(eventId);
return Results.Ok(new { status = "success" });
});
Integration Examples
Handle events by EventType, and use CustomerId / OrderId to keep your records in sync when email addresses change.
- JavaScript
- Python
- C#
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);
}
}
def handle_pulse_event(event: dict) -> None:
event_type = event['EventType']
customer_id = event['CustomerId']
order_id = event['OrderId']
order_item_id = event['OrderItemId']
contact = event['ContactPerson']
if event_type in ('NewOrder', 'NewSubscription'):
upsert_customer(customer_id, contact)
create_order(customer_id, order_id, order_item_id, event)
elif event_type == 'SubscriptionRenewal':
# Same CustomerId / OrderId as the original subscription
record_renewal(customer_id, order_id, event)
elif event_type == 'SubscriptionCancellation':
revoke_access(customer_id, order_id)
elif event_type in ('Refund', 'DisputeLost'):
record_credit(customer_id, order_id, event)
elif event_type == 'DisputeCreated':
record_dispute_opened(customer_id, order_id, event)
elif event_type == 'DisputeWon':
record_dispute_won(customer_id, order_id, event)
else:
print(f'Unhandled event type: {event_type}')
public void HandlePulseEvent(PulseWebhookEvent eventData)
{
switch (eventData.EventType)
{
case "NewOrder":
case "NewSubscription":
UpsertCustomer(eventData.CustomerId, eventData.ContactPerson);
CreateOrder(eventData.CustomerId, eventData.OrderId, eventData.OrderItemId, eventData);
break;
case "SubscriptionRenewal":
// Same CustomerId / OrderId as the original subscription
RecordRenewal(eventData.CustomerId, eventData.OrderId, eventData);
break;
case "SubscriptionCancellation":
RevokeAccess(eventData.CustomerId, eventData.OrderId);
break;
case "Refund":
case "DisputeLost":
RecordCredit(eventData.CustomerId, eventData.OrderId, eventData);
break;
case "DisputeCreated":
RecordDisputeOpened(eventData.CustomerId, eventData.OrderId, eventData);
break;
case "DisputeWon":
RecordDisputeWon(eventData.CustomerId, eventData.OrderId, eventData);
break;
default:
Console.WriteLine($"Unhandled event type: {eventData.EventType}");
break;
}
}
public class PulseWebhookEvent
{
public int ProductId { get; set; }
public int PricePlanId { get; set; }
public int OrderItemId { get; set; }
public int OrderId { get; set; }
public int CustomerId { get; set; }
public int TransactionId { get; set; }
public decimal Amount { get; set; }
public string Currency { get; set; }
public decimal Discount { get; set; }
public int Quantity { get; set; }
public string EventType { get; set; }
public BillingContact ContactPerson { get; set; }
}
Retries and Reconciliation
If your endpoint is unreachable or returns a non-2xx status:
- Pulse retries the first three failures 30 seconds apart
- Further attempts use exponential backoff (2m → 5m → 15m → 1h → 3h → 6h → 12h…) for up to 3 days from the first attempt
- A
410 Goneresponse marks the delivery as permanently failed (no further automatic retries) - Exhausted deliveries appear under Settings → Webhooks → Failed deliveries
- 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
| Scenario | HTTP status from your endpoint | Pulse behavior | Action |
|---|---|---|---|
| Accepted | 2xx | Marked delivered | None |
| Temporary failure | 5xx / timeout | Retried with backoff | Fix endpoint; check Failed deliveries if exhausted |
| Validation error | 400 | Retried with backoff | Fix payload handling |
| Unauthorized | 401 | Retried with backoff | Check signature verification and signing secret |
| Not found | 404 | Retried with backoff | Verify webhook URL in Settings |
| Endpoint retired | 410 | Permanently failed | Update or delete the webhook; optional Replay after fix |
| Duplicate delivery | 2xx after idempotent no-op | Marked delivered | Deduplicate 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-Idand ignore duplicates - Key records by
CustomerIdandOrderId, not email alone - Return
2xxquickly — do heavy work asynchronously after acknowledging - Return
410only 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.