Webhooks

Quickstart

Get up and running with Pelcro webhooks in three steps:

1. Create an endpoint that accepts POST requests and returns a 200 status code:

// PHP
// Laravel
Route::post('/webhooks/pelcro', function (Request $request) {
    $event = $request->all();
    Log::info("Received {$event['type']} event: {$event['id']}");

    // Acknowledge receipt immediately
    // Process the event asynchronously (e.g., dispatch a queued job)
    ProcessWebhookEvent::dispatch($event);

    return response('OK', 200);
});

# Flask
@app.route('/webhooks/pelcro', methods=['POST'])
def handle_webhook():
    event = request.get_json()
    print(f"Received {event['type']} event: {event['id']}")

    # Acknowledge receipt immediately
    # Process the event asynchronously (e.g., enqueue a task)
    process_event.delay(event)

    return 'OK', 200

// Express
app.post('/webhooks/pelcro', (req, res) => {
  const event = req.body;
  console.log(`Received ${event.type} event: ${event.id}`);

  // Acknowledge receipt immediately
  res.status(200).send('OK');

  // Process the event asynchronously
  processEvent(event);
});

2. Register your URL in the Pelcro Platform under Settings > Notifications. Create a new webhook endpoint, enter your URL, then select the events you want to receive.

3. Verify signatures to confirm events are from Pelcro (see Signature Verification below).

That's it. Pelcro will now send an HTTP POST request to your endpoint every time a subscribed event occurs.

Configuration

You can register webhook endpoints from Settings > Notifications in the Pelcro Platform. Although you can subscribe to all events, this is not recommended as it will put unnecessary pressure on your server. Configure your webhook to listen to only the events required by your integration. You can also subscribe to webhooks via the API.

When registering the URL, it must respond with successful status code (2xx) to the POST requests in order to pass the initial validation.

Once you register a webhook URL with Pelcro, we will issue an HTTP POST request to the URL specified every time that event occurs, and your endpoint is expected to answer in a timely fashion by returning a successful status code (2xx). Any other status code is considered a failure.

Payload Structure

Every webhook event follows the same envelope structure:

{
    "type": "subscription.created",
    "id": "evt_ybR5i5QwSVvoWy28ndD4q6hA",
    "created": 1542034347,
    "data": {
        "object": {
            "object": "subscription",
            "id": 6807,
            "user_id": 40864,
            "plan_id": 386,
            "cancel_at_period_end": false,
            "canceled_at": null,
            "current_period_end": "2024-02-01T00:00:00.000000Z",
            "current_period_start": "2024-01-01T00:00:00.000000Z"
        }
    }
}

For events that include change tracking (e.g., subscription.changed, customer.updated), the payload also includes a data.previous_attributes object with the field values before the change.

The webhook is sent with the following headers:

Content-Type: application/json
X-Pelcro-Hmac-SHA256: pdvcCMQA5298lNhqp7i52StRjHEKgY7Z77yU+f+lfGQ=

Events Ordering

The order in which events are delivered to endpoints is not related to the order they were triggered on our system. For example, the logical flow of events triggered while creating a subscription might be the following:

• subscription.created
• invoice.created
• charge.created

Your integration shouldn't assume delivery of events in the order specified in the example above, and needs to handle processing accordingly.

Delivery and Retries

Timeouts

Your endpoint must respond quickly. Pelcro enforces the following timeouts:

Your endpoint should acknowledge receipt of the event immediately by returning a 2xx status code, then process the event asynchronously in a background job or queue. Do not perform business logic (API calls, database operations, emails) before responding.

Retry Behavior

If your endpoint fails to return a 2xx status code, Pelcro will retry the delivery up to 3 attempts. Retries are processed immediately through our queue system with no delay between attempts. After all attempts are exhausted, the delivery is marked as permanently failed.

🚧

No exponential backoff

Retries happen in quick succession. If your endpoint is temporarily down, all 3 attempts may fail before it recovers. Make sure your endpoint is highly available, and monitor your webhook delivery statuses in the Pelcro Platform.

Statuses

Various circumstances can cause webhook event delivery to enter a specific status. Refer to the table below for information on each status.

Best Practices

• Return 2xx immediately, then process events in a background queue.
• Use the id field for idempotency. Your endpoint may receive the same event more than once. Store processed event IDs and skip duplicates.
• Subscribe only to events you need. This reduces load on your server and simplifies your integration.
• Monitor delivery statuses in the Pelcro Platform to catch endpoint failures early.

Signature Verification

Pelcro signs every webhook event by including an HMAC-SHA256 signature in the X-Pelcro-Hmac-SHA256 header. This allows you to verify that events were sent by Pelcro, not by a third party.

How it works

1. Extract the base64-encoded signature from the X-Pelcro-Hmac-SHA256 header.
2. Compute an HMAC-SHA256 hash using your webhook signing secret as the key and the raw JSON request body as the message.
3. Compare your computed signature with the one from the header.
4. Return a 2xx status code to acknowledge receipt. Pelcro will retry up to 3 times on failure.

Code Examples

// PHP

$payload = file_get_contents('php://input');
$secret  = 'your_webhook_secret';

$expected = base64_encode(
    hash_hmac('sha256', $payload, $secret, true)
);

$signature = $_SERVER['HTTP_X_PELCRO_HMAC_SHA256'] ?? '';

if (!hash_equals($expected, $signature)) {
    http_response_code(401);
    exit('Invalid signature');
}

http_response_code(200);

// Process the event
$event = json_decode($payload, true);

const crypto = require('crypto');

app.post('/webhooks/pelcro', (req, res) => {
  const payload   = JSON.stringify(req.body);
  const secret    = 'your_webhook_secret';
  const signature = req.headers['x-pelcro-hmac-sha256'];

  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('base64');

  if (expected !== signature) {
    return res.status(401).send('Invalid signature');
  }

  res.status(200).send('OK');

  // Process the event
  const event = req.body;
});

import hmac
import hashlib
import base64

payload   = request.get_data()  # raw request body
secret    = b'your_webhook_secret'
signature = request.headers.get('X-Pelcro-Hmac-SHA256', '')

expected = base64.b64encode(
    hmac.new(secret, payload, hashlib.sha256).digest()
).decode()

if not hmac.compare_digest(expected, signature):
    abort(401, 'Invalid signature')

return 'OK', 200

require 'openssl'
require 'base64'

payload   = request.body.read
secret    = 'your_webhook_secret'
signature = request.env['HTTP_X_PELCRO_HMAC_SHA256']

expected = Base64.strict_encode64(
  OpenSSL::HMAC.digest('sha256', secret, payload)
)

unless Rack::Utils.secure_compare(expected, signature)
  halt 401, 'Invalid signature'
end

status 200

🚧

Use constant-time comparison

Always use a constant-time string comparison function (like hash_equals in PHP, hmac.compare_digest in Python, or Rack::Utils.secure_compare in Ruby) to prevent timing attacks.

Events

Below is a complete list of all events we currently send to your configured webhook endpoint. Select an event's resource page to see the full JSON payload. Please note that we may change, delete, or add more at any time. While developing and maintaining your code, keep an eye on the changelog.

Addresses

Bills

Campaigns

Charges

Customers

Exports

Fraud Prevention

Invoices

Members

Newsletters

Orders

Payment Methods

Plans

Products

Subscriptions

Vendors

Security

For added security, your integration should make sure the events it receives originate from Pelcro's infrastructure. See the list of outgoing IP addresses to whitelist.