Docs » API endpoints (beta)

This is a beta feature!

The API gives you powerful control over your data, which means it can be highly destructive. Remember, Webhook makes nightly backups of your data should you ever need to revert.

Also, please be prudent with your usage. As a beta product, the API is not configured to handle large numbers of requests. Each update will trigger a site build. If you're looking for heavy importing, please use our Import tools instead.

Overview

The Webhook API allows you to manipulate your CMS data through scripts or third party services. We've provided an example of importing Tweets into your site farther down in this document. To use the API you'll need to find your API key, which is in the CMS under 'Backups and Data'.

The API Key is in the "Backups and Data" portion of your CMS.

The Webhook API exposes four end points that allow you to build, insert, update and delete content from your site's data schema.

Build Site

Note

API builds, whether triggered by this command, or through inserting items will only rebuild your live website, not your local development environment. You can mimic the rebuild by hitting save anywhere in your CMS after data is inserted through the API.

This is the endpoint used to trigger a build for a site immediately, there is no data associated with this request, just query string parameters.

Format

  • URL: https://server.webhook.com/build/
  • Request Type: POST
  • Query String Parameters:
    • site: The name of the site to build
    • apiKey: The API Key for the site
  • Post Data: None

Curl Example

curl -X POST  https://server.webhook.com/build/?site=siteName&apiKey=12345

Insert an Item

This endpoint can be used to insert data into the database. You can either insert a new item into a list of items, or if you insert a one off you can overwrite the one off that is already there. The format of the data being inserted is a JSON object in the same way as described in the importing section of our documentation, with some important exceptions for dates. The exceptions for the data are as follows:

  1. You do not need to specify last_updated, _sort_last_udpated, create_date, or _sort_create_date. These will all be set to the date you call this API function automatically.
  2. You do not need to specify _sort_publish_date. This will be automatically generated for you.
  3. The publish_date field accepts more types of strings for time. Anything moment.js accepts we accept, as well as the special now string that will set it to the time of the API call. If no publish_date is specified, the item will be created as a draft.

Format

  • URL: https://server.webhook/add-item/
  • Request Type: POST
  • Query String Parameters:
    • site: The name of the site to build
    • apiKey: The api key for the site
    • type: The name of the type we're inserting data for. Remember to use the id name, not the display name. Usually this is lowercase and all one word.
  • Post Data: A JSON object representing the data being inserted, as described above.

Curl Example

curl -X POST -H "Content-Type: application/json" -d '{"publish_date": "now", "name" : "Name of Item"}' \
https://server.webhook.com/add-item/?site=mySiteName&apiKey=12345&type=contentTypeName

Update an Item

This endpoint can be used to update already existing data in the database. The format of the data being posted is the same as described in the Insert an Item section. If you do not specify a field in the data, that field will not be changed on the item.

Format

  • URL: https://server.webhook/update-item/
  • Request Type: POST
  • Query String Parameters
    • site: The name of the site to build
    • apiKey: The api key for the site
    • type: The name of the type we're updating. Remember to use the id name, not the display name. Usually this is lowercase and all one word.
    • id: The id of the object to update (for one offs this should be the same as the typename)
  • Post Data: A JSON object representing the data being inserted, as described above.

Curl Example

curl -X POST -H "Content-Type: application/json" -d '{"publish_date": "10-2-1990 10:00:00"}' \
https://server.webhook.com/update-item/?site=mySiteName&apiKey=12345&type=contentTypeName&id=-JbDZYVn5DfPDEGbDXhD

Delete an Item

This endpoint can be used to delete an already existing item in the database. There is no data in the POST request for this API call. This call can not be used to delete one offs (as one offs can not be deleted)

Format

  • URL: https://server.webhook/delete-item/
  • Request Type: POST
  • Query String Parameters:
    • site: The name of the site to build
    • apiKey: The api key for the site
    • type: The name of the type we're deleting. Remember to use the id name, not the display name. Usually this is lowercase and all one word.
    • id: The id of the object to delete
  • Post Data: None

Curl Example

curl -X POST  \
https://server.webhook.com/delete-item/?site=mySiteName&apiKey=12345&type=contentTypeName&id=-JbDZYVn5DfPDEGbDXhD

API in practice: importing tweets using Zapier

Our API endpoints allow you to "pipe" data between services to import data into webhook dynamically. In this example we'll be using Zapier to import tweets into our test site. Zapier has other integrations for other popular services, but they should all follow a similar ste-by-step setup as this Twitter one.

1. Create a new Content Type in Webhook

For this example we'll create a Content Type called Tweet with the fields Name, Tweet URL and Tweet Body. We'll use Webhook's default publish_date field to store the datetime the tweet was entered.

Create a basic Webhook form called "Tweet".

2. Use Zapier to create a Zap between Twitter and Webhook

Note that the term "Web Hook" is different from the "Webhook" CMS. "Web Hooks" are URL based triggers that perform an action on a server. In this case you're using web hooks to push content into the Webhook CMS.

The next step is to create a "Zap" between Twitter and our API. We'll want to set up our Zap to trigger every time a tweet happens, and we'll want our action to send a post request to an API endpoint similar this.

Set up a "Web Hook" for Webhook. :D

3. Configure the post action

Now that we have the trigger properly set up let's configure the POST action to send data to our site's "Insert Data" endpoint. The first step is to set the URL to the endpoint's URL, along with the siteName, apiKey, and type query string parameters:

Substitute in your site name and API key.

Next we need to configure the POST data to map the data between Twitter and the Tweet content type we set up earlier. Because Webhook requires a name field at all times, we'll set the name to the id of the tweet, the tweet_url field as the URL of the tweet, and we'll set the publish_date to "now" so that the tweet is immediately published. If you want the tweet's original post time you could also store that by making new fields.

Notice that we're mapping the Webhook field name slugs "tweet_body" instead of "Tweet Body".

4. Activate the Zap, test a tweet.

Finally turn on the Zap and after posting a new tweet to Twitter we should get a new entry added to our Tweet content type in the CMS.

Tweets move from Twitter to Zapier and finally into the Webhook CMS.

The tweet is now available in our CMS, with enough information for us to refer to it into our templates (of course we can import any other information that Zapier exports from Twitter). Also because every API call forces a build, your frontend should also update with the new data according to your template design.


This is just a small example of what you can do with Webhook's API. Hopefully this gives you a general idea of how to chain events together through services like Zapier or through your own scripts.