Ping Extension (optional)

Optional extension to WebSub that periodically pings subscriptions

Optionally we can ping your subscriptions to make sure they are still working. This can be useful in a production setup, since it can help us detect errors early, and notify you.

To setup a subscription that will be pinged, use hub.ext.ping query param in the subscription request as described in the documentation. After that the callback endpoint will be periodically pinged by us.

Ping request

Your callback URL will be periodically called using all three methods (GET, DELETE, PUT) to make sure that it's all working and getting through correctly.

The ping requests will have an extra HTTP header set X-Hub-Ext-Ping with a value of true. And the body will be made up of a special "ping NewsItem" without any real content, that we use to test that HMAC verification, JSON decoding works and then respond to the challenge.

{
  "news_id": "00000000-0000-0000-0000-000000000000",
  "content": {
    "slug": "ping-challenge-[value]"
  },
  "properties": {
    "type": "ping"
  },
  "source": "mfn"
}

Ping response

To respond successfully to a ping, the response should be a JSON object containing the following values. And if the subscription was made with a hub.secret the body should be signed using the same shared secret and sent back with the X-Hub-Signature response header.

JSON Path	Content
pong.method	Echo back the HTTP method from the request (case insensitive) POST / PUT / DELETE
pong.challenge	Echo back the challange value extracted from content.slug in the ping request

The metadata object can contain any content. The fields user_agent and version are recommended but totally optional. The contents of both are freeform.

{
  "pong": {
    "method": "put",
    "challenge": "[value]",
  },
  "metadata": {
     "user_agent": "mfn-wp-plugin",
     "version": "0.0.53",
  },
}