Integrations & Publishing
Using Webhooks for Custom Integrations
Webhooks are a powerful way to automate your workflow by sending real-time data from our platform to other applications. While we offer many native integrations, webhooks allow you to connect with custom platforms, internal databases, or any service that can receive an HTTP request.
This guide is intended for users who want to build custom integrations. You may need some basic knowledge of APIs and web development to set this up effectively.
What are Webhooks?
Think of a webhook as a "reverse API." Instead of your application asking our platform for data, our platform "pushes" data to your application as soon as an event happens. For example, when a new article is generated or an SEO analysis is completed, a webhook can immediately notify your custom dashboard or CMS.
By using webhooks, you eliminate the need for "polling" (constantly checking for updates), which saves resources and ensures your data is always up to date.
Prerequisites
Before you begin setting up a custom integration, ensure you have the following:
A Destination URL: This is the endpoint on your server or third-party platform that will receive the data. It must be a public URL and use HTTPS for security.
Server Access: You need the ability to configure your server to receive and process POST requests.
Authentication Strategy: Decide how you will verify that the data is coming from us (we recommend using Webhook Secrets).
Step 1: Accessing Webhook Settings
To start configuring your custom integration, you first need to find the Webhooks section in your account settings.
Log in to your dashboard.
Navigate to Settings in the sidebar.
Select the Integrations & Publishing tab.
Click on Webhooks.
If you don't see the Webhooks option, check your plan details. Webhooks are typically available on Pro and Enterprise plans.
[Screenshot Placeholder: The Webhooks settings page showing the "Add Webhook" button]
Step 2: Adding a New Webhook
Once you are in the Webhooks section, click the Add Webhook button to open the configuration form.
Destination URL
Enter the full URL of your endpoint. This is where we will send the JSON payload.
Example: https://your-app.com/api/webhooks/receive
Webhook Secret
We highly recommend entering a Secret Key. This key is used to create an HMAC signature for every request we send. Your server can use this signature to verify that the request is legitimate and hasn't been tampered with.
[Screenshot Placeholder: The Add Webhook form with URL and Secret fields]
Step 3: Selecting Event Triggers
You don't have to receive data for everything that happens in your account. You can choose specific events that are relevant to your custom integration. Common events include:
content.generated: Triggered when a new piece of content is ready.analysis.completed: Triggered when an SEO or keyword analysis finishes.publishing.failed: Triggered if an automated publish to a native integration fails.
Subscribing only to the events you need reduces the load on your server and makes your integration easier to maintain.
Step 4: Configuring Custom Headers (Optional)
Some platforms require specific headers for authentication or routing (e.g., X-API-Key or Authorization). You can add these key-value pairs in the Custom Headers section of the setup form.
[Screenshot Placeholder: Custom Headers configuration section]
Step 5: Testing and Saving
Before finalizing, use the Test Connection button. We will send a "ping" or a sample payload to your URL. If your server responds with a 200 OK status, the connection is successful.
Once verified, click Save Webhook. Your integration is now live!
Understanding the Payload Format
All webhooks are sent as an HTTP POST request with a Content-Type: application/json header. The body of the request contains a JSON object with the following structure:
{ "event": "content.generated", "created_at": "2024-05-20T14:30:00Z", "delivery_id": "evt_12345abcde", "data": { "id": "art_98765", "title": "How to Use Webhooks", "status": "completed", "url": "https://app.platform.com/articles/98765" } }
Key Fields:
event: The type of action that triggered the webhook.delivery_id: A unique identifier for this specific delivery. Use this to prevent processing the same event twice (idempotency).data: The actual information related to the event. The fields inside this object will vary depending on the event type.
Security Best Practices
When building custom integrations, security should be your top priority. Follow these guidelines to keep your data safe:
1. Verify Signatures
If you provided a Secret Key during setup, every request will include an X-Hub-Signature-256 header. This is an HMAC-SHA256 hash of the request body, signed with your secret. Your server should calculate its own hash and compare it to the header before processing the data.
2. Use HTTPS
Never use a plain HTTP URL for webhooks. HTTPS ensures that the data sent between our platform and your server is encrypted in transit.
3. IP Whitelisting
If your server is behind a strict firewall, you may need to whitelist our IP addresses to allow webhook traffic through. Please contact support for our current list of outgoing IP ranges.
Always validate the data received in a webhook before using it in sensitive operations, such as updating a database or triggering a payment.
Handling Deliveries and Retries
To ensure reliability, your server must respond to our webhook requests quickly and correctly.
Response Timeouts
Your server must respond with a 2xx status code (like 200 OK) within 10 seconds. If your server takes longer or returns an error code (4xx or 5xx), we will consider the delivery a failure.
Retry Logic
If a delivery fails, our system will automatically attempt to resend the webhook. We use an exponential backoff strategy, meaning the time between retries increases after each failure. After a certain number of failed attempts (usually 5), the delivery will be marked as "Failed" and no further attempts will be made for that specific event.
Asynchronous Processing
If your integration needs to perform a long-running task (like generating a PDF or calling another API), do not do it while the webhook request is open. Instead, receive the webhook, respond with a 200 OK immediately, and then process the data in the background using a task queue.
Troubleshooting Common Issues
If your webhooks aren't working as expected, check the following:
Check the Logs: Most platforms provide a "Webhook History" or "Logs" tab where you can see the status of past deliveries and the exact error message returned by your server.
Firewall Blocks: Ensure your server isn't blocking requests from our IP addresses.
SSL Certificate: If your SSL certificate is expired or self-signed, the connection may fail. Use a valid certificate from a provider like Let's Encrypt.
Payload Size: Very large payloads might be truncated or rejected by some servers. Ensure your endpoint can handle JSON bodies up to 5MB.
Conclusion
Webhooks provide the flexibility to build deeply customized workflows that fit your unique business needs. By following the steps and best practices outlined in this guide, you can create robust, secure, and real-time integrations with any platform.
For more advanced use cases or specific API documentation, please visit our Developer Portal or reach out to our technical support team.