schedulR news publication to a homepage using a webhook

schedulR can make an HTTP/HTTPS POST request to your endpoint when news article will be published to homepage channel or canceled. In order to use homepage channel you have to generate signing key and enter URL of you endpoint, responsible for processing the webhook.

If you intend to utilize the homepage channel in schedulR, you'll need to take the following steps:

• Generate a signing key: Create a secure signing key that will be used to verify the authenticity of the webhook requests.
• Enter the endpoint URL: Specify the URL of the endpoint in your application that will be responsible for processing the webhook. This is the destination where schedulR will send the HTTP/HTTPS POST request.

By completing these two steps, schedulR will be able to notify your system via the specified endpoint whenever a news article is published or canceled on the homepage channel.

Error handling​

To handle errors effectively when receiving webhook requests from schedulR, the following error handling mechanism is in place. schedulR expects a 2xx response code from your endpoint to confirm the successful publication of the channel. If schedulR receives a non-2xx response code from your endpoint, it will automatically retry posting the event. The retries will be attempted 9 times, with specific intervals between each attempt: 1 minutes, 2 minutes, 5 minutes, 10 minutes, 30 minutes, 1 hour, 2 hours, 4 hours, 8 hours. If all the retry attempts fail, schedulR will mark the channel publication as failed.

Payload​

Publish​

When a news is published, you will receive a "published" event along with a corresponding payload:

Example

{
  "signature": {
    "timestamp": 1688650505,
    "token": "PxclxcPsyWUwG1BwNuSQOOLkA6SjTaKEbp3oUjFD5Qk9im6YRD",
    "signature": "f81af360fdf2cbaa3f7793646676c4054096cf80ea3c29683db463fa2532d913"
  },
  "event": "publish",
  "data": {
    "id": 69,
    "name": "Title newasdasdasd",
    "author": "schedulR Admin",
    "news_date": "2023-07-06",
    "news_datetime": "2023-08-01T06:56:11+00:00",
    "ad_hoc": true,
    "tags": [
      {
        "id": 23,
        "name": "Tech"
      },
      {
        "id": 32,
        "name": "Markets"
      }
    ],
    "translations": [
      {
        "language": "en",
        "title": "Example Title DE",
        "header": "<p>Example header</p>",
        "content": "<p>Example content</p>",
        "footer": "<p>Example footer</p>",
        "thumbnail": "https://example.com/7e7443ef-ea79-4262-8cf2-e102d514a18c.png",
        "created_at": "2023-07-06T13:33:36+00:00",
        "updated_at": "2023-07-06T13:33:36+00:00",
        "attachments": [
          {
            "name": "Attachment Name",
            "url": "https://example.com/51de172c-a5d7-481a-a4cb-96895ba77dc6.pdf"
          }
        ],
        "ad_hoc_text": "Ad hoc announcement"
      },
      {
        "language": "de",
        "title": "Example Title DE",
        "header": "<p>Example header</p>",
        "content": "<p>Example content</p>",
        "footer": "<p>Example footer</p>",
        "thumbnail": "https://example.com/ebe882e5-f7c2-42b8-b250-981b6271b10f.png",
        "created_at": "2023-07-06T13:33:41+00:00",
        "updated_at": "2023-07-06T13:33:45+00:00",
        "attachments": [],
        "ad_hoc_text": "Ad hoc announcement"
      }
    ],
    "created_at": "2023-07-06T13:33:18+00:00",
    "updated_at": "2023-07-06T13:34:55+00:00"
  }
}

Cancel​

When a news publication is canceled or a news item is deleted you will receive 'cancel' event with the following payload:

Example

{
  "signature": {
    "timestamp": "1688650495",
    "token": "p9rXhuo4ncGoIuxKzMxT6LrxV4Ae1AaKDiuK6uPBjFaQ6Kk83K",
    "signature": "dd20913f6d6ee27fdc33732c601861218bc96893592d44925c06cade409471bc"
  },
  "event": "cancel",
  "data": {
    "id": 69
  }
}

Security​

To guarantee the authenticity of the requests, schedulR schedulR applies a signing process to each request:

To verify the webhook is originating from schedulR, follow these steps:

• Concatenate the timestamp and token values together.
• Apply the HMAC algorithm to the combined string using your Signing Key as the key and SHA256 digest mode.
• Compare the resulting hexdigest with the provided signature.
• Optionally, you can also verify that the timestamp is relatively close to the current time.

Signature verification examples​

function verify(string $signingKey, int $timestamp, string $token, string $signature): bool
{
    $hmacDigest = hash_hmac('sha256', $timestamp.$token, $signingKey);

    return $hmacDigest === $signature;
}

import crypto from 'node:crypto';

const verify = ({ signingKey, timestamp, token, signature }) => {
    const encodedToken = crypto
        .createHmac('sha256', signingKey)
        .update(timestamp.concat(token))
        .digest('hex')

    return (encodedToken === signature)
}

import hashlib, hmac

def verify(signing_key, token, timestamp, signature):
    hmac_digest = hmac.new(key=signing_key.encode(),
                           msg=('{}{}'.format(timestamp, token)).encode(),
                           digestmod=hashlib.sha256).hexdigest()
    return hmac.compare_digest(str(signature), str(hmac_digest))

require 'openssl'

def verify(signing_key, token, timestamp, signature)
  digest = OpenSSL::Digest::SHA256.new
  data = [timestamp, token].join
  signature == OpenSSL::HMAC.hexdigest(digest, signing_key, data)
end

package main

import (
	"crypto/hmac"
	"crypto/sha256"
	"encoding/hex"
)

func verify(signingKey, token, timestamp, signature string) bool {
	h := hmac.New(sha256.New, []byte(signingKey))
	h.Write([]byte(timestamp + token))
	calculatedSignature := hex.EncodeToString(h.Sum(nil))

	return signature == calculatedSignature
}

Development & Testing​

We recommend testing the webhook in our dedicated test environment. Please reach out to us so we can set you up accordingly there.