Developer API

Webhook API

We've implemented a very simple and easy-to-use method, namely webhooks, of sending posts into a user account for storage as either a scheduled post or a queue post.

Creating Webhooks

The user must create a webhook with Posting, Webhooks in her account, and then provide the webhook URL to your app or service.

Posting Text-Only Content To Webhooks

(See also the Posting Image & Video Content To Webhooks below.)

All text-only content requests to webhooks must be SSL POST requests, with a Content-Type header of application/json, and a JSON payload.

The following two fields are allowed:

  • title - string
  • body - string

If a webhook is directly connected to a social profile or blog, then the post will be published immediately. If the webhook is connected to a queue, then the post will be added at the end of the queue. Providing a specific publishing date and time via the API is not possible.

Sample JSON Body

{
  "title": "Nam auctor porta nisi, ut rutrum enim dignissim et.",
  "body": "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed non nisl sit amet ligula faucibus placerat."
}

Which Fields For Which Social Networks

  • Discord, Facebook, LinkedIn, Mastodon, Twitter
    • body - HTML code is automatically removed by the API.
  • Tumblr, WordPress.com, WordPress.org
    • title - HTML code is automatically removed by the API.
    • body - HTML code is automatically converted to Markdown by the API.

Posting Image & Video Content To Webhooks

All image & video content requests to webhooks must be SSL POST requests, with a Content-Type header of multipart/form-data.

The following POST field must be present:

  • json_payload - JSON encoded string

The JSON encode string consists of the following two fields:

  • title - string
  • body - string

Example using cURL:

CURLOPT_POSTFIELDS => array('media_file'=> new CURLFILE('file_name.png'), 'json_payload' => '{"title"::The post title", "body":"The post body"}')

See the section "Which Fields For Which Social Networks" for which fields to include in the json_payload field.

If a webhook is directly connected to a social profile or blog, then the post will be published immediately. If the webhook is connected to a queue, then the post will be added at the end of the queue. Providing a specific publishing date and time via the API is not possible.

Which Fields For Which Social Networks

  • Discord, Facebook, LinkedIn, Mastodon, Twitter
    • body - HTML code is automatically removed by the API.
  • Tumblr, WordPress.com
    • title - HTML code is automatically removed by the API.
    • body - HTML code is automatically converted to Markdown by the API.

Text Encoding

Text must be encoded in UTF-8 format.

Authentication

Webhooks don't require authentication or registration of your app or service. If a user wants to remove your access to their webhook, they would simply delete the webhook from their account.

Rate Limits

All webhook API requests are rate limited. Rate limits are per individual webhook.

We return HTTP response headers containing the rate limit details on every API request.

Response Rate Limit Headers

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 54
X-RateLimit-Reset: 1554475218
  • X-RateLimit-Limit: The number of requests that can be made.
  • X-RateLimit-Remaining: The number of remaining requests that can be made.
  • X-RateLimit-Reset: Epoch time (seconds since 00:00:00 UTC on January 1, 1970) at which the rate limit resets.

When you exceed the rate limit, the request will be rejected with a 429 HTTP response code and a JSON body.

Response To Rate Limited Request

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1554475218
{
  "message": "You are being rate limited.",
  "retry_after": 7456
}
  • retry_after: The number of seconds before another request should be made.

Do not continue to make requests to the webhook after the first 429 HTTP response code. Back off and wait until the rate limit resets before making the next request.

Making Money As A Developer

Feel free to register as an affiliate of SocialOomph, and earn recurring referral fees!

Fee free to develop a paid service or app that makes use of our API. We don't want a cut of your income.