Skip to main content
Custom API / Webhook lets technical teams connect Serpy to a custom publishing workflow. Use it if your website does not use a standard CMS or if your team wants to receive published content through an endpoint.

​
What Custom API / Webhook is for

Custom API / Webhook is useful for custom websites, internal CMS systems, or technical publishing workflows. It lets Serpy send article content to an endpoint your team controls. This can be useful for:
  • custom-built websites
  • internal publishing systems
  • headless CMS workflows
  • developer-managed websites
  • custom content pipelines

​
Who should use it

Use Custom API / Webhook if you have a developer or technical team that can receive and process content. If you use WordPress, Shopify, Webflow, Wix, Framer, Sanity, or Supabase, a standard CMS integration may be easier.

​
How the publishing flow works

The flow is simple:
  1. You add an endpoint URL in Serpy.
  2. You choose the authentication type if needed.
  3. You save and test the connection.
  4. When you publish from the Content Editor, Serpy sends the article data to your endpoint.
  5. Your system receives the request.
  6. Your system creates, updates, stores, or publishes the content.
Serpy sends the content. Your system decides what to do with it.

​
Endpoint URL

The endpoint URL is the URL Serpy will send the publish request to. Example: https://example.com/api/serpy/publish Your endpoint should accept a POST request.

​
Method

Serpy sends a POST request to your endpoint. Your endpoint should be prepared to receive JSON.

​
Headers

Serpy sends the request as JSON. Typical headers include:
  • Content-Type: application/json
If you use authentication, additional headers may be included depending on your setup.

​
Authentication

Authentication helps protect your endpoint. Depending on your setup, you may use options such as:
  • no authentication
  • bearer token
  • API key
  • custom header
Your developer should choose the option that matches your website or backend.

​
Publish payload

When an article is published, Serpy sends article data to your endpoint. The payload may include fields such as:
  • article title
  • slug
  • HTML content
  • plain text or markdown content when available
  • meta title
  • meta description
  • featured image URL
  • additional image URLs
  • publish status
  • scheduled date when available
  • website ID
  • article ID
  • content type
Example payload: 
{
  "event": "content.publish",
  "article": {
    "id": "article_123",
    "title": "Best SEO Tools for Small Businesses",
    "slug": "best-seo-tools-small-businesses",
    "content_html": "<h1>Best SEO Tools for Small Businesses</h1><p>...</p>",
    "content_markdown": "# Best SEO Tools for Small Businesses\n\n...",
    "meta_title": "Best SEO Tools for Small Businesses",
    "meta_description": "Compare SEO tools for small businesses and find the right option for your team.",
    "content_type": "listicle",
    "featured_image_url": "https://cdn.example.com/image.png",
    "image_urls": [
      "https://cdn.example.com/image.png"
    ],
    "status": "publish",
    "scheduled_at": null
  },
  "website": {
    "id": "website_123",
    "name": "Example Website",
    "url": "https://example.com"
  }
}

​
Scheduled content

If the article is scheduled, Serpy may include a scheduled date. Your system can use that date to schedule the post or store it as a draft until the publish time. Example: 
{
  "status": "scheduled",
  "scheduled_at": "2026-07-01T14:00:00Z"
}

​
Expected response

Your endpoint should return a success response when the content is received. A successful response should use a 2xx status code. Example response: 
{
  "success": true,
  "external_id": "post_456",
  "url": "https://example.com/blog/best-seo-tools-small-businesses"
}
The external_id and url are useful if your system creates a post and wants to return the created page details.

​
Error response

If your system cannot accept the content, return an error response. Example: 
{
  "success": false,
  "error": "Missing required field: title"
}
Use clear error messages so your team can understand what needs to be fixed.

​
Testing the connection

Before publishing real content, test the connection. Testing helps confirm that:
  • Serpy can reach your endpoint
  • authentication works
  • your endpoint accepts JSON
  • your system can process the request
  • the response format is valid

​
What your system should do with the content

Your system can decide how to handle the article. Common options include:
  • create a draft post
  • publish immediately
  • schedule for later
  • store the article in a database
  • send the article into an approval workflow
  • map the content into a headless CMS

​
Tips

Use Custom API / Webhook only if you have technical support. Start by creating drafts instead of publishing immediately. Log incoming requests while testing. Make sure your endpoint can handle HTML content and image URLs. Return clear success or error responses. Keep authentication details secure.