Webhooks

Automate your workflow by receiving real-time notifications when events occur in penr.ai.

Overview

Webhooks allow you to integrate penr.ai with external services by sending HTTP POST requests when specific events happen.

Supported Events

Event	Description
Content Created	When new content is generated or imported
Content Updated	When content is edited and saved
Content Published	When content is published to a site
Content Scheduled	When content is scheduled for future publication
Keyword Created	When a new keyword is discovered or added
Keyword Approved	When a keyword is moved to approved status
Site Connected	When a new site is connected

Creating a Webhook

1. Navigate to Settings > Webhooks
2. Click Create Webhook
3. Configure your webhook:
   • Name: A descriptive name for this webhook
   • URL: The endpoint that will receive the POST requests
   • Events: Select which events should trigger this webhook
4. Click Save

A signing secret will be automatically generated for security.

Webhook Configuration

Signing Secret

Each webhook has a unique signing secret used to verify that requests are authentic. The secret is used to generate an HMAC-SHA256 signature included in the request headers.

To regenerate a secret:

1. Open the webhook settings
2. Click Regenerate Secret
3. Update your receiving endpoint with the new secret

Active/Inactive Toggle

You can temporarily disable a webhook without deleting it. Inactive webhooks won't send any requests.

Testing Webhooks

Click Test on any webhook to send a test payload to your endpoint. This helps verify your integration is working correctly.

Webhook Logs

View the delivery history for each webhook:

• Last 10 deliveries shown
• Status indicator: Green (success) or Red (failure)
• Event type: Which event triggered the delivery
• HTTP status: Response code from your endpoint
• Duration: How long the request took (in milliseconds)
• Timestamp: When the delivery occurred

Verifying Webhook Signatures

To verify that a webhook request is authentic:

1. Extract the signature from the X-Webhook-Signature header
2. Compute the HMAC-SHA256 hash of the request body using your signing secret
3. Compare the computed hash with the signature

Example (Node.js):

const crypto = require('crypto');

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

Best Practices

• Always verify signatures to ensure requests are from penr.ai
• Respond quickly (within 5 seconds) to avoid timeouts
• Return a 2xx status to indicate successful receipt
• Handle duplicates gracefully - the same event may be sent multiple times
• Use HTTPS endpoints for security