Guide: Using Webhooks

Webhooks let you receive real-time notifications when events occur in your PageGun project.

Supported Events

Event	Trigger
`page.created`	A new page is created
`page.updated`	A page is updated
`page.published`	A page is published
`page.unpublished`	A page is unpublished
`page.deleted`	A page is deleted

Setting Up a Webhook

Configure webhooks in your project settings:

curl -X PUT "https://api.pagegun.com/v1/projects/YOUR_PROJECT_ID/settings" \
  -H "Authorization: Bearer $PAGEGUN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "webhooks": [
      {
        "url": "https://your-server.com/webhooks/pagegun",
        "events": ["page.published", "page.updated"],
        "secret": "your_webhook_secret"
      }
    ]
  }'

Webhook Payload

When an event fires, PageGun sends a POST request to your URL:

{
  "event": "page.published",
  "timestamp": "2024-01-21T09:00:00Z",
  "data": {
    "id": "page_xyz789",
    "page_name": "My Page",
    "slug": "my-page",
    "type": "article",
    "status": "published"
  }
}

Verifying Signatures

Each webhook includes an X-PageGun-Signature header. Verify it using your webhook secret:

const crypto = require('crypto');

function verifyWebhook(payload, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

Best Practices

Always verify signatures to ensure requests are from PageGun
Respond with 200 quickly — process webhooks asynchronously
Handle retries — PageGun retries failed deliveries up to 3 times
Use a queue for high-volume projects to avoid overwhelming your server