> ## Documentation Index
> Fetch the complete documentation index at: https://docs.genseo.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks

> Connect Genseo to external services using webhooks for advanced automation

## 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.

<video controls className="w-full aspect-video rounded-xl" src="https://videos.genseo.co/integrations/Webhook-Integration.mov" />

## 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:

```json theme={null}
{
  "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

* Learn about [article publishing](/articles/publish-articles)
* Explore [automation workflows](/calendar/auto-publish)
* Review the [Public API documentation](/developers/public-api) for advanced integrations