Pulses

Pulses are webhook notifications that allow you to receive real-time HTTP POST requests when specific events occur in your Chariow store. Instead of constantly polling the API, Pulses push event data to your configured endpoint URL as soon as something happens, enabling you to build responsive integrations and automations.

How Pulses Work

Event Occurs

An event happens in your store (e.g., a sale is completed).

Pulse Triggered

Chariow sends a signed HTTP POST request to your configured endpoint.

Verify the Signature

Your server checks the x-chariow-signature header before trusting the payload.

Process the Event

Your server deduplicates on x-pulse-delivery-id and processes the payload.

Acknowledge Receipt

Your server returns a 2xx status code to confirm receipt.

Your endpoint URL is public, so anyone who discovers it can post to it. Always verify the signature before acting on a payload — see Pulse Security.

Request Headers

Every delivery carries these headers:

Header	Contents
`x-chariow-signature`	`sha256=<hex digest>` — HMAC-SHA256 of the raw body
`x-pulse-id`	The Pulse identifier, e.g. `pulse_abc123`
`x-pulse-delivery-id`	The delivery identifier — your idempotency key
`x-pulse-event`	The event name, e.g. `successful.sale`
`Content-Type`	`application/json; charset=utf-8`
`User-Agent`	`Pulse \| Chariow +https://chariow.com`

Full signing contract, verification snippets and troubleshooting: Pulse Security.

Setting Up Pulses

You can configure Pulses in several ways:

Via Store Dashboard

Go to Automation → Pulses
Click Add Pulse
Enter your webhook endpoint URL (must be HTTPS)
Select the events you want to receive
Optionally select specific products (leave empty for all products)
Save your Pulse

Your Pulse endpoint must be accessible via HTTPS. HTTP endpoints are not supported for security reasons.

Pulse Events

Pulses support the following events. When an event fires, the webhook payload contains an event field with the event value.

Sale Events

Event Value	Label	Description
`successful.sale`	Successful Sale	Triggers when a sale is completed
`abandoned.sale`	Abandoned Sale	Triggers when a sale is abandoned
`failed.sale`	Failed Sale	Triggers when a sale fails

License Events

Event Value	Label	Description
`license.activated`	License Activated	Triggers when a license is activated
`license.expired`	License Expired	Triggers when a license expires
`license.issued`	License Issued	Triggers when a license is issued to a customer
`license.nearing_expiry`	License Nearing Expiry	Triggers when a license is approaching its expiry date
`license.revoked`	License Revoked	Triggers when a license is revoked

Affiliate Events

Event Value	Label	Description
`affiliate.joined`	Affiliate Joined	Triggers when a new affiliate joins your store

You can configure multiple events for a single Pulse URL. When any of the selected events occur, Chariow will send a webhook notification to your endpoint with the corresponding event value.

Pulse Payload

When a configured event occurs, Chariow sends an HTTP POST request to your webhook URL with event data in the request body. The exact payload structure depends on the event type.

Pulse payloads contain comprehensive event data, including details about the entity (sale, license, etc.), customer information, product details, and store context. The payload structure varies by event type to provide relevant information for each event.

Successful Sale Example

When a successful sale occurs, Chariow sends a webhook with the successful.sale event:

{
  "event": "successful.sale",
  "sale": {
    "id": "sal_xyz789abc",
    "amount": {
      "value": 99,
      "formatted": "$99.00",
      "short": "99",
      "currency": "USD"
    },
    "original_amount": {
      "value": 99,
      "formatted": "$99.00",
      "short": "99",
      "currency": "USD"
    },
    "discount_amount": {
      "value": 0,
      "formatted": "$0.00",
      "short": "0",
      "currency": "USD"
    },
    "settlement": {
      "amount": {
        "value": 89.10,
        "formatted": "$89.10",
        "short": "89",
        "currency": "USD"
      },
      "due_at": "2025-01-22T10:30:00+00:00",
      "done_at": null,
      "service_fee": {
        "value": 4.95,
        "formatted": "$4.95",
        "short": "5",
        "currency": "USD"
      },
      "payment_fee": {
        "value": 4.95,
        "formatted": "$4.95",
        "short": "5",
        "currency": "USD"
      },
      "fee": {
        "value": 9.90,
        "formatted": "$9.90",
        "short": "10",
        "currency": "USD"
      }
    },
    "status": "completed",
    "created_at": "2025-01-15T10:30:00+00:00",
    "custom_fields": null,
    "custom_metadata": {"order_ref": "ORD-123"},
    "completed_at": "2025-01-15T10:32:00+00:00",
    "abandoned_at": null,
    "failed_at": null
  },
  "product": {
    "id": "prd_def456",
    "name": "Premium Course",
    "url": "https://mystore.mychariow.com/p/premium-course",
    "price": {
      "value": 99,
      "formatted": "$99.00",
      "short": "99",
      "currency": "USD"
    }
  },
  "customer": {
    "id": "cus_abc123",
    "name": "John Doe",
    "first_name": "John",
    "last_name": "Doe",
    "email": "customer@example.com",
    "phone": "+1234567890",
    "country": "US"
  },
  "affiliate": null,
  "store": {
    "id": "str_xyz789",
    "name": "My Digital Store",
    "url": "https://mystore.mychariow.com"
  },
  "checkout": {
    "url": "https://mystore.mychariow.com/checkout/sal_xyz789abc"
  }
}

License Activated Example

When a license is activated, Chariow sends a webhook with the license.activated event:

{
  "event": "license.activated",
  "license": {
    "id": "lic_ghi789def",
    "key": "ABCD-1234-EFGH-5678",
    "status": "active",
    "source_type": "sale",
    "activation_count": 1,
    "max_activations": 5,
    "activated_at": "2025-01-15T10:35:00+00:00",
    "expires_at": "2026-01-15T10:35:00+00:00",
    "expired_at": null,
    "revoked_at": null,
    "created_at": "2025-01-15T10:30:00+00:00"
  },
  "product": {
    "id": "prd_def456",
    "name": "Pro Software License",
    "url": "https://mystore.mychariow.com/p/pro-software"
  },
  "customer": {
    "id": "cus_abc123",
    "name": "John Doe",
    "first_name": "John",
    "last_name": "Doe",
    "email": "customer@example.com",
    "phone": "+1234567890",
    "country": "US"
  },
  "store": {
    "id": "str_xyz789",
    "name": "My Digital Store",
    "url": "https://mystore.mychariow.com"
  }
}

License Nearing Expiry Example

Chariow scans licenses daily and sends the license.nearing_expiry event once per license, as soon as it enters the seven-day window before its expires_at date. Use it to prompt a renewal before the customer loses access.

days_until_expiry is only present on this event. It is rounded up, so a license lapsing in a few hours reports 1. A license is announced once and only once, even if the scan runs again before it expires.

{
  "event": "license.nearing_expiry",
  "days_until_expiry": 7,
  "license": {
    "id": "lic_ghi789def",
    "key": "ABCD-1234-EFGH-5678",
    "status": "active",
    "source_type": "sale",
    "activation_count": 1,
    "max_activations": 5,
    "activated_at": "2025-01-15T10:35:00+00:00",
    "expires_at": "2026-01-15T10:35:00+00:00",
    "expired_at": null,
    "revoked_at": null,
    "created_at": "2025-01-15T10:30:00+00:00"
  },
  "product": {
    "id": "prd_def456",
    "name": "Pro Software License",
    "url": "https://mystore.mychariow.com/p/pro-software"
  },
  "customer": {
    "id": "cus_abc123",
    "name": "John Doe",
    "first_name": "John",
    "last_name": "Doe",
    "email": "customer@example.com",
    "phone": "+1234567890",
    "country": "US"
  },
  "store": {
    "id": "str_xyz789",
    "name": "My Digital Store",
    "url": "https://mystore.mychariow.com"
  }
}

Affiliate Joined Example

When a new affiliate joins your store, Chariow sends a webhook with the affiliate.joined event:

{
  "event": "affiliate.joined",
  "affiliate": {
    "id": "saff_xyz789abc",
    "account": {
      "id": "aff_abc123def",
      "code": "CREATOR123",
      "pseudo": "creative_studio",
      "email": "creator@example.com",
      "first_name": "John",
      "last_name": "Doe",
      "name": "John Doe",
      "country": {
        "code": "US",
        "name": "United States"
      },
      "phone": {
        "country_code": "US",
        "formatted": "+1 234 567 890"
      }
    },
    "source": "invitation",
    "status": "active",
    "joined_at": "2025-01-15T10:40:00+00:00"
  },
  "store": {
    "id": "str_xyz789",
    "name": "My Digital Store",
    "url": "https://mystore.mychariow.com"
  }
}

The exact payload structure may include additional fields depending on the event type and context. Always check the actual payload received at your endpoint for the complete data structure.

Handling Pulses

Basic Example (Node.js/Express)

const express = require('express');
const app = express();

app.post('/webhooks/chariow', express.json(), (req, res) => {
  const payload = req.body;
  const event = payload.event;

  switch (event) {
    case 'successful.sale':
      handleSuccessfulSale(payload.sale, payload.product, payload.customer, payload.store);
      break;
    case 'abandoned.sale':
      handleAbandonedSale(payload.sale, payload.store);
      break;
    case 'failed.sale':
      handleFailedSale(payload.sale, payload.store);
      break;
    case 'license.activated':
      handleLicenseActivated(payload.license, payload.product, payload.customer);
      break;
    case 'license.expired':
      handleLicenseExpired(payload.license, payload.customer);
      break;
    case 'license.issued':
      handleLicenseIssued(payload.license, payload.product, payload.customer);
      break;
    case 'license.nearing_expiry':
      handleLicenseNearingExpiry(payload.license, payload.customer, payload.days_until_expiry);
      break;
    case 'license.revoked':
      handleLicenseRevoked(payload.license, payload.customer);
      break;
    case 'affiliate.joined':
      handleAffiliateJoined(payload.affiliate, payload.store);
      break;
    default:
      console.log(`Unhandled event type: ${event}`);
  }

  // Always return 200 to acknowledge receipt
  res.status(200).send('OK');
});

function handleSuccessfulSale(sale, store) {
  console.log(`Sale completed: ${sale.id} in store ${store.name}`);
  // Add customer to CRM, send confirmation email, grant access, etc.
}

function handleLicenseActivated(license, customer) {
  console.log(`License activated: ${license.key} for ${customer.email}`);
  // Log activation, update internal records, notify customer, etc.
}

function handleLicenseNearingExpiry(license, customer, daysUntilExpiry) {
  console.log(`License ${license.key} expires in ${daysUntilExpiry} day(s)`);
  // Send a renewal reminder, create a renewal offer, flag the account, etc.
}

function handleAffiliateJoined(affiliate, store) {
  console.log(`New affiliate joined: ${affiliate.account.code} in store ${store.name}`);
  // Send welcome email, create affiliate dashboard access, notify team, etc.
}

app.listen(3000, () => console.log('Webhook server running on port 3000'));

PHP Example

<?php

// Read the raw POST data
$payload = file_get_contents('php://input');
$data = json_decode($payload, true);

$event = $data['event'] ?? null;

switch ($event) {
    case 'successful.sale':
        handleSuccessfulSale($data['sale'], $data['product'], $data['customer'], $data['store']);
        break;
    case 'abandoned.sale':
        handleAbandonedSale($data['sale'], $data['store']);
        break;
    case 'failed.sale':
        handleFailedSale($data['sale'], $data['store']);
        break;
    case 'license.activated':
        handleLicenseActivated($data['license'], $data['product'], $data['customer']);
        break;
    case 'license.expired':
        handleLicenseExpired($data['license'], $data['customer']);
        break;
    case 'license.issued':
        handleLicenseIssued($data['license'], $data['product'], $data['customer']);
        break;
    case 'license.nearing_expiry':
        handleLicenseNearingExpiry($data['license'], $data['customer'], $data['days_until_expiry']);
        break;
    case 'license.revoked':
        handleLicenseRevoked($data['license'], $data['customer']);
        break;
    case 'affiliate.joined':
        handleAffiliateJoined($data['affiliate'], $data['store']);
        break;
    default:
        error_log("Unhandled event type: " . $event);
}

// Always return 200 to acknowledge receipt
http_response_code(200);
echo 'OK';

function handleSuccessfulSale($sale, $store) {
    error_log("Sale completed: {$sale['id']} in store {$store['name']}");
    // Add customer to CRM, send confirmation email, grant access, etc.
}

function handleLicenseActivated($license, $customer) {
    error_log("License activated: {$license['key']} for {$customer['email']}");
    // Log activation, update internal records, notify customer, etc.
}

function handleLicenseNearingExpiry($license, $customer, $daysUntilExpiry) {
    error_log("License {$license['key']} expires in {$daysUntilExpiry} day(s)");
    // Send a renewal reminder, create a renewal offer, flag the account, etc.
}

function handleAffiliateJoined($affiliate, $store) {
    error_log("New affiliate joined: {$affiliate['account']['code']} in store {$store['name']}");
    // Send welcome email, create affiliate dashboard access, notify team, etc.
}

Retry Policy

If your endpoint doesn’t respond with a 2xx status code, Chariow retries the delivery. A delivery gets 5 attempts in total, spaced with an exponential backoff:

After attempt	Next attempt in
1st	10 seconds
2nd	100 seconds
3rd	~17 minutes
4th	~2 hours 47 minutes

Each attempt times out after 30 seconds. The signature is computed once at dispatch and reused unchanged by every retry, so a retry landing hours later still verifies.

After the 5th failed attempt on a single delivery, the Pulse is disabled automatically and the store owner, admins and marketing team members receive an email. You must re-enable it from the dashboard before it fires again — and before you can replay its deliveries.

Ensure your Pulse endpoint responds quickly (within 30 seconds). Long-running processes should be handled asynchronously.

Delivery History and Replay

Every attempt is recorded, so you can see whether Chariow ever called your endpoint and what it answered. Open Automations → Pulses → select your Pulse → Deliveries tab. The table lists each delivery with:

Field	Meaning
`status`	`pending`, `succeeded` or `failed`
`http_status_code`	The status code your endpoint returned
`attempts`	How many attempts have been made so far
`payload`	The exact body that was sent
`response_body`	Your endpoint’s response, truncated
`is_replay`	Whether this delivery was triggered by a manual replay

pending means queued or mid-retry, not failed. A delivery only becomes failed once all 5 attempts are exhausted.

Clicking a row opens the sent payload, the response and the delivery id. Replay re-sends a stored payload to the same endpoint without reprocessing the original sale or licence event — useful when your endpoint was down, or while you are debugging signature verification.

A replay is a new delivery with a new x-pulse-delivery-id, so it passes your idempotency check and will be processed again. That is intentional.

Best Practices

Respond Quickly

Return a 200 response immediately, then process the Pulse asynchronously to avoid timeouts:

app.post('/webhooks/chariow', (req, res) => {
  // Acknowledge receipt immediately
  res.status(200).send('OK');

  // Process asynchronously (e.g., queue job, background worker)
  queuePulseProcessing(req.body);
});

Handle Duplicates

Due to retry logic, the same delivery may reach you more than once. Deduplicate on the x-pulse-delivery-id header, which is stable across every attempt of a delivery:

const processedDeliveries = new Set();

async function processPulse(deliveryId, payload) {
  if (processedDeliveries.has(deliveryId)) {
    console.log('Duplicate delivery, skipping');
    return;
  }

  processedDeliveries.add(deliveryId);
  // Process the pulse...
}

Do not deduplicate on the entity id inside the payload: one sale legitimately produces one delivery per subscribed Pulse.

Verify the Signature

Never act on a payload before checking x-chariow-signature. See Pulse Security for the full contract and ready-to-use snippets.

Use HTTPS

Always use HTTPS for your Pulse endpoint to ensure data is encrypted in transit. Chariow will reject HTTP endpoints for security reasons.

Monitor Failures

Check the Deliveries tab of your Pulse regularly. It shows the status code and response body of every attempt, so you can diagnose failures without adding logging on your side.

Filter by Products

For high-volume stores, consider creating separate Pulses for different products to make processing more efficient and organised.

Testing Pulses

Use the Pulse testing feature in your dashboard:

Go to Automations → Pulses
Click on your Pulse
Click Send test pulse
Check your endpoint received the test payload

A test event is signed exactly like a real one, but it carries no x-pulse-delivery-id header (no delivery record is created for it) and its payload contains an extra note field. To validate your integration against a real payload, replay a delivery from the Deliveries tab instead.

For local development, use a service like ngrok to expose your local server to the internet.

Managing Pulses via API

You can programmatically manage your Pulses using the Chariow Public API:

List All Pulses

curl -X GET "https://api.chariow.com/v1/pulses" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example List Response

{
  "data": [
    {
      "id": "pls_abc123xyz",
      "url": "https://example.com/webhooks/chariow",
      "is_enabled": true,
      "source": {
        "value": "manual",
        "label": "Manual",
        "description": "Created manually"
      },
      "triggers": [
        {
          "value": "successful_sale",
          "label": "Successful Sale",
          "description": "Triggers when a sale is completed"
        }
      ],
      "products": [
        {
          "id": "prd_def456",
          "name": "Premium Course",
          "type": "course",
          "pictures": {
            "thumbnail": "https://cdn.chariow.com/products/thumb.jpg",
            "cover": "https://cdn.chariow.com/products/cover.jpg"
          },
          "category": {
            "value": "education_and_learning",
            "label": "Education and Learning"
          },
          "pricing": {
            "type": "one_time",
            "price": {
              "value": 99,
              "formatted": "$99.00",
              "short": "99",
              "currency": "USD"
            },
            "effective": {
              "value": 99,
              "formatted": "$99.00",
              "short": "99",
              "currency": "USD"
            }
          },
          "bundle": null,
          "metadata": null
        }
      ],
      "store": {
        "id": "str_xyz789",
        "name": "My Digital Store",
        "logo_url": "https://cdn.chariow.com/stores/xyz789/logo.png",
        "url": "https://mystore.mychariow.com"
      },
      "is_editable": true,
      "created_at": "2025-01-10T08:00:00+00:00",
      "updated_at": "2025-01-10T08:00:00+00:00"
    }
  ],
  "pagination": {
    "next_cursor": null,
    "prev_cursor": null,
    "has_more": false
  }
}

Get a Specific Pulse

curl -X GET "https://api.chariow.com/v1/pulses/pls_abc123xyz" \
  -H "Authorization: Bearer YOUR_API_KEY"

The response for a single pulse uses the same structure as each item in the list response.

Filter Pulses

You can filter pulses by URL or event type using the search parameter:

curl -X GET "https://api.chariow.com/v1/pulses?search=successful_sale" \
  -H "Authorization: Bearer YOUR_API_KEY"

For complete API documentation, see the List Pulses and Get Pulse endpoints.

Pulse Security

Verify signatures and deduplicate retries

API Reference - List Pulses

View detailed API documentation

API Reference - Get Pulse

Get a specific pulse via API

Sales Guide

Learn about sale events

Licenses Guide

Learn about license events

Affiliates Guide

Learn about affiliate events

Introduction

Guides

MCP Integration

n8n Integration

Resources

How Pulses Work

Request Headers

Setting Up Pulses

Via Store Dashboard

Pulse Events

Sale Events

License Events

Affiliate Events

Pulse Payload

Successful Sale Example

License Activated Example

License Nearing Expiry Example

Affiliate Joined Example

Handling Pulses

Basic Example (Node.js/Express)

PHP Example

Retry Policy

Delivery History and Replay

Best Practices

Testing Pulses

Managing Pulses via API

List All Pulses

Example List Response

Get a Specific Pulse

Filter Pulses

Pulse Security

API Reference - List Pulses

API Reference - Get Pulse

Sales Guide

Licenses Guide

Affiliates Guide

​How Pulses Work

​Request Headers

​Setting Up Pulses

​Via Store Dashboard

​Pulse Events

​Sale Events

​License Events

​Affiliate Events

​Pulse Payload

​Successful Sale Example

​License Activated Example

​License Nearing Expiry Example

​Affiliate Joined Example

​Handling Pulses

​Basic Example (Node.js/Express)

​PHP Example

​Retry Policy

​Delivery History and Replay

​Best Practices

​Testing Pulses

​Managing Pulses via API

​List All Pulses

​Example List Response

​Get a Specific Pulse

​Filter Pulses

​Related Resources

Pulse Security

API Reference - List Pulses

API Reference - Get Pulse

Sales Guide

Licenses Guide

Affiliates Guide

How Pulses Work

Request Headers

Setting Up Pulses

Via Store Dashboard

Pulse Events

Sale Events

License Events

Affiliate Events

Pulse Payload

Successful Sale Example

License Activated Example

License Nearing Expiry Example

Affiliate Joined Example

Handling Pulses

Basic Example (Node.js/Express)

PHP Example

Retry Policy

Delivery History and Replay

Best Practices

Testing Pulses

Managing Pulses via API

List All Pulses

Example List Response

Get a Specific Pulse

Filter Pulses

Related Resources