Webhook integration

How webhook publishing works

Spron sends every ready article to each active webhook automatically. Your endpoint receives the complete article, its metadata, and image links in a signed request, then decides how to save or publish that content.

New posts have article.action set to new. Updates use refresh, while article.id stays unique to the article so your endpoint can update the same post.

Edits are saved as you type but are not sent automatically after publication. Press Republish in the article editor to send the latest version.

• Automatic retries keep the same Idempotency-Key, which your endpoint can use to avoid making a second copy.
• A manual Retry delivery sends the latest saved HTML as a new delivery.
• Return {"published_url":"https://your-site.com/post"} after publishing so Spron can mark the article as published.

Before you connect a webhook

You need an HTTPS address that accepts POST requests. The address can belong to your own site, a CMS, or an automation tool.

A workspace owner or admin must add and manage the webhook. Other workspace members can ask an owner or admin to complete the connection.

Plan to store the access token when Spron displays it. Spron shows this token only once, and your endpoint needs it to check incoming requests.

• Prepare a receiving endpoint, such as https://example.com/api/spron.
• Make sure the endpoint can read the raw request body if you plan to verify X-Spron-Signature.
• Save incoming images in your own media library before publishing. Spron image links work for one hour.

Connect Webhook to Spron

1. Add your address

   Open the Webhook integration and press Add webhook. Enter a Connection name and the full Webhook address, then press Connect webhook.

   Spron sends a POST request to this address whenever an article is ready. If you cannot add the connection, ask a workspace owner or admin.

2. Save the access token

   Copy the token from Save your webhook access token and store it securely. Add it to your receiving endpoint as the Bearer token.

   Do this before closing the token dialog because Spron will not show the token again.

3. Check each request

   Compare the Bearer token and verify the signature before trusting or publishing the content. For X-Spron-Signature, create an HMAC-SHA256 digest from the raw body with your token and compare it with the received value.

   In Node.js, the Spron receiver package on npm can handle this check.

   npm install @spron/receiver

4. Send your first article

   Press Send test event on the webhook row first. Once your endpoint receives it, press Publish in an article or use Send pending to send articles that were ready before you connected.

What Spron sends

Spron sends the article content, publishing metadata, media details, and delivery headers your endpoint needs. The formatted article appears in article.content_html, with the same current article also available in article.content_markdown.

The request includes article.title, article.keyword, article.meta_description, article.images, and article.featured_image. It can also include article.video when the article has one and article.target_url for the page to update.

Each image entry includes a link, alt text, and caption. Your receiver should download the image while its link remains available.

• X-Spron-Event is article.ready for an article and webhook.test for a test event.
• Authorization contains Bearer YOUR_ACCESS_TOKEN.
• X-Spron-Signature contains an HMAC-SHA256 signature of the raw body in the form sha256=<hex>.
• Webhook-Id, Webhook-Timestamp, and Webhook-Signature let you check the delivery ID, signing time, and body together.
• Idempotency-Key stays the same during automatic retries.

Check your first published post

Use Spron's test event and delivery history to check the connection before relying on automatic publishing. On the webhook row, press Send test event and confirm that your endpoint receives a request with X-Spron-Event set to webhook.test.

Next, press Publish in an article or use Send pending. Open Delivery history to see the article, webhook, result, and sent time.

Results can appear as Waiting, Sending, Sent, Published, or Needs attention. After your endpoint publishes the post, check its title, content, images, and saved URL at the destination.

• Use the displayed delivery error when a result shows Needs attention.
• For a completed or failed delivery on an active webhook, an owner or admin can press Retry delivery.
• Confirm that your endpoint updates an existing post when it receives the same article.id.

Fix common Webhook connection issues