Skip to main content

​
Overview

Webhooks allow you to connect Genseo to external services like Slack, Notion, or custom dashboards. At the moment, Genseo emits exactly one webhook per article—the moment the article is actually published (including scheduled auto-publishes). Use that single payload to trigger downstream automation.

​
Setting Up Webhooks

​
Step 1: Create the Connection in Genseo

  1. Navigate to Settings → Integrations
  2. Click the Webhooks tile and then Connect
  3. A configuration window opens where you enter:
    • Webhook URL: The HTTPS endpoint that will receive events
    • Authentication: Choose between NONE, BEARER TOKEN, API KEY, BASIC AUTH, or CUSTOM HEADER
    • Headers / Secrets: Provide the necessary credentials based on your chosen auth type
  4. Select the event types you want to subscribe to
  5. (Optional) Click Send test to deliver a sample payload to your endpoint and confirm it responds correctly
  6. Click Save to store the configuration

​
Step 2: Verify Webhook

When the configuration is saved, Genseo sends a verification request to your endpoint. Your endpoint must respond with the provided challenge token to complete the setup.

​
Webhook Payload

Genseo sends webhook events when articles are published. Here’s an example payload for the post.published event: 
{
  "event": "post.published",
  "timestamp": "2025-11-19T19:46:59.878Z",
  "data": {
    "id": "test-post-id-123",
    "title": "Test Blog Post",
    "content": "This is a test blog post to verify your webhook integration is working correctly.",
    "keyword": "test keyword",
    "meta_title": "Test Meta Title",
    "meta_description": "Test Meta Description",
    "thumbnail": "https://example.com/test-image.jpg",
    "published_at": "2025-11-19T19:46:59.878Z"
  }
}

​
Payload Fields

  • event: The event type (e.g., post.published)
  • timestamp: ISO 8601 timestamp of when the event occurred
  • data.id: Unique identifier for the published post
  • data.title: The article title
  • data.content: The full article content (HTML or markdown)
  • data.keyword: The target keyword for the article
  • data.meta_title: SEO meta title
  • data.meta_description: SEO meta description
  • data.thumbnail: URL to the article thumbnail image
  • data.published_at: ISO 8601 timestamp of when the article was published

​
Authentication

Genseo signs all webhook payloads with an HMAC-SHA256 signature. Verify the signature to ensure the webhook came from Genseo.

​
Verifying Signatures

  1. Get your webhook secret from Genseo settings
  2. Create an HMAC-SHA256 hash of the raw request body using your secret
  3. Compare the hash with the signature in the signature header

​
Best Practices

​
Security

  • Verify signatures: Always verify webhook signatures to ensure requests are from Genseo
  • Use HTTPS: Only use HTTPS endpoints for webhooks
  • Validate data: Validate all incoming data before processing
  • Rate limiting: Implement rate limiting on your webhook endpoint

​
Reliability

  • Idempotency: Make your webhook handlers idempotent to handle duplicate events
  • Retries: Genseo retries failed webhooks, so handle duplicate events gracefully
  • Error handling: Return appropriate HTTP status codes (200 for success, 4xx/5xx for errors)
  • Logging: Log all webhook events for debugging

​
Performance

  • Async processing: Process webhooks asynchronously when possible
  • Queue system: Use a queue system for heavy processing
  • Timeout handling: Respond quickly to webhook requests (within 5 seconds)

​
Troubleshooting

​
Webhooks Not Firing

Problem: Webhooks aren’t being sent to your endpoint. Solution:
  • Verify your webhook URL is correct and accessible
  • Check that your endpoint is returning 200 status codes
  • Review webhook logs in Genseo settings
  • Ensure your webhook is enabled and subscribed to the correct events

​
Invalid Signature Errors

Problem: Signature verification fails. Solution:
  • Verify you’re using the correct webhook secret
  • Ensure you’re hashing the raw request body (not parsed JSON)
  • Check that you’re using HMAC-SHA256
  • Verify the signature format matches: sha256=<hash>

​
Duplicate Events

Problem: Receiving duplicate webhook events. Solution:
  • Implement idempotency in your webhook handler
  • Use event IDs to track processed events
  • Handle retries gracefully (Genseo may retry failed webhooks)

​
Next Steps