Webhook Integration Guide

Webhooks allow your external applications to receive real-time notifications when events happen on your Postion site. Use them to automate workflows, sync data with your CRM, trigger emails, and more.

What Are Webhooks?

A webhook is an HTTP callback — when a specific event occurs on Postion (like a new subscriber or a purchase), we send a POST request to a URL you specify with data about that event.

Setting Up Webhooks

Step 1: Create a Webhook Endpoint

1. Go to Dashboard → Webhooks
2. Click "Add Webhook"
3. Enter your endpoint URL (e.g., https://your-app.com/api/postion-webhook)
4. Select the events you want to receive

Step 2: Choose Your Events

Step 3: Verify Your Endpoint

After creating the webhook, Postion sends a verification request to your URL. Your endpoint must respond with a 200 OK status to confirm it's ready.

Webhook Payload Format

All webhook payloads follow this structure:

{
  "event": "subscriber.created",
  "timestamp": "2025-07-15T10:30:00Z",
  "data": {
    "id": "sub_abc123",
    "email": "[email protected]",
    "name": "Jane Doe",
    "plan": "pro",
    "site_id": "site_xyz789"
  }
}

Security: Verifying Webhook Signatures

Every webhook request includes a signature header (X-Postion-Signature) that you should verify to ensure the request is genuinely from Postion.

import crypto from 'crypto';
 
function verifyWebhookSignature(payload, signature, secret) {
  const hash = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  return hash === signature;
}

Common Integration Patterns

Sync with Your CRM

When a subscriber signs up, automatically create a contact in your CRM:

1. Listen for subscriber.created events
2. Extract the subscriber's email and name
3. Create or update the contact in your CRM (HubSpot, Salesforce, etc.)

Send Welcome Emails via Custom Service

Trigger a personalized welcome email through your own email service:

1. Listen for subscriber.created events
2. Use the subscriber data to personalize the email
3. Send via your preferred email provider (SendGrid, Mailgun, etc.)

Slack Notifications

Get notified in Slack when key events occur:

1. Create a Slack Incoming Webhook URL
2. Set up a middleware that receives Postion webhooks
3. Forward formatted messages to your Slack channel

Analytics Tracking

Log events to your analytics platform:

1. Listen for all relevant events
2. Forward to Mixpanel, Amplitude, or your custom analytics
3. Build dashboards to track subscriber lifecycle

Retry Policy

If your endpoint is unavailable, Postion retries with exponential backoff:

After 5 failed attempts, the webhook is marked as failing, and you'll receive an email notification.

Troubleshooting

"Webhook not receiving events"

• Verify your endpoint URL is publicly accessible (not localhost)
• Check that your endpoint returns a 200 status code within 10 seconds
• Ensure the correct events are selected in your webhook settings

"Invalid signature"

• Make sure you're using the correct webhook secret from your dashboard
• Verify you're computing the HMAC on the raw request body, not parsed JSON

"Events arriving out of order"

Webhooks may arrive out of order due to network conditions. Use the timestamp field to determine the true sequence of events.

For the full API reference, see our Public API Documentation. For technical details about the webhook system architecture, see Webhooks Architecture.