Applications: Versioning



We feel that versioning webhook implementations is as important as versioning your API - yet virtually no one implements versioning. Since the concept of webhooks is quite new most companies have not had several iterations of the implementation which more than likely is why we are not seeing versioning.

Creating different specifications for each version is of course very easy to do and our system will help organize this for you.

  • version [mandatory]: text string of the version of the API. Typically will be a number or date formatted value.
  • configuration_instructions [optional]: Instructions on how to configure webhooks from within your web application. This will provide the user the basic instructions so they can get going using webhooks.
  • outgoing_messages (collection) [mandatory]: Contains details regarding the way the outgoing messages are formatted.
    • ssl_required (boolean)[mandatory]: Indicates if the outgoing endpoint is required to be using SSL.
    • content_types (collection)[optional]: The content types that the outgoing message supports. This is typically JSON and/or XML.
      • type (string)[optional]: The content type which would be one of json or xml.
      • headers_included (collection)[optional]: The headers that are included in the outgoing messages for this specific content type.
    • standard_headers (collection)[optional]: The standard headers that are included in all outgoing messages, regardless of content type.
    • retry_policies (collection)[optional]: Defines the retry polices that can be implemented.
      • policy_id (string)[optional]: The id for the policy that is implemented.
      • title (string)[optional]: A human readable title for the policy.
      • details (string)[optional]: The details regarding the policy which can include an explanation on how the policy operates.
    • authentication (collection)[optional]: Defines the type of authentication that the outgoing messages can contain.
      • type (string)[optional]:
      • details (string)[optional]: The information regarding the general authentication process for the webhooks.
      • options (collection)[optional]: A collection that contains an object defining each of the authentication types that can be used for outgoing messages.
        • token (or any other valid type)
  • responses (collection)[mandatory]: Defines the type of responses that are valid.
    • details (string)[optional]: The general overview of how responses should be handled. This can be a long explanation to help add any context required.
    • codes (collection)[mandatory]: Details the types of codes that are considered successful and failed requests.
      • success (array)[mandatory]: An array of HTTP status codes that are considered successful requests. The following syntax is acceptable 2XX as well as individual entries such as 200 or 201.
      • failure (array)[mandatory}: An array of HTTP status codes that are considered failed requests. The same syntax rules as the success requests above apply.
  • events (collection)[mandatory]: Details each type of event for which a webhook can be fired. In addition, can outline what is expected within that event and provide sample payloads.
    • details (string)[optional]: The general overview about how events are handled, etc.
    • key_location (collection)[mandatory]: Helps to define where the event key data is located for each different type of payload that is supported - ie JSON & XML.
      • {payload type (json|xml|csv)} (collection)[optional]: Contains the location and variable for the specific payload type.
        • location (string)[mandatory]: This should indicate where the event details are located, options include payload, header, and query_string.
        • variable (string)[mandatory]: Indicates the actual variable that contains the event details. If the location is payload, then this value should be represented in dot notation to the point of the value. If the location is header or query_string this value should be the actual name of the variable the value is contained within in the header or query_string.
    • options (array)[mandatory]: An array that contains all the different event options that are possible for the webhooks.
      • title (string)[mandatory]: This should contain the general grouping for the options. For example the value might be "Accounts" which would mean this section is all webhooks that are related to accounts.
      • events (array)[mandatory]: An array containing all the events that are related to this option.
        • key (string)[mandatory]: The key value that is sent along with the webhook that identifies this event. For example a key that signals an account was updated might be "account.updated".
        • label (string)[mandatory]: The friendly title that describes this particular event.
        • details (string)[optional}: Details regarding this particular event explaining the payload or when the event is fired, etc.
        • payloads (collection)[optional]: This collection should contain a key for each payload type that the webhooks support. This will allow developers to see a sample payload for the webhook they would receive.
          • {payload type (json|xml|csv)} (collection|string)[optional]: Depending on the payload type, if it is JSON this should be the JSON representation of the payload. If the value is XML or something else this should be a string value that represents the payload. You can also utilize the payload templates feature. This allows you to create one template that will be used for multiple payload types to streamline development. If specifying a template the syntax should be "template:{key}".
  • payload_templates (array)[optional]: Defines one or more payload templates that can be reused in the sample event payloads above. This helps avoid repetitive authoring of payloads.
    • type(string)[mandatory]: The type of payload that is being defined.
    • {payload type (json|xml|csv)} (collection|string)[optional]: Depending on the payload type, if it is JSON this should be the JSON representation of the payload. If the value is XML or something else this should be a string value that represents the payload.
  • example_cases (array)[optional]: Provides a means to outline some example business processes and detail which webhooks would be fired. This allows for grouping as well to create multiple variations for business processes.
    • group_name(string)[mandatory]: The name of the business process or general group name.
    • cases(array)[mandatory]: An array containing each example case within the group.
      • title(string)[mandatory]: The title of the case.
      • overview(string)[mandatory]: Any additional details that are required to further describe the case.
      • events(array)[mandatory]: An array that includes all the events that would be fired when this business process/case is executed. The events should be in the order in which they would fire in the actual system.

####Sample JSON

The sample JSON is for a fictitious application called "MyAwesomeApp"

{
  "version" : "1",
  "configuration_instructions" : "Webhooks can be configured in the webhook settings section of the MyAwesomeApp dashboard. Clicking Add URL will reveal a form to add a new URL for receiving webhooks.  You can enter any URL you'd like to have receive the events. The mode determines whether test events or live events are sent to this URL — if you want to send both live and test events to the same URL you need to create two separate settings (application webhooks do not follow this rule). You may add as many URLs as you like.",
  "outgoing_messages" : {
    "ssl_required" : false,
    "content_types" : [
      {
        "type" : "json",
        "headers_included" : [
          {
            "Content-Type" : "application/json; charset=utf-8"
          }
        ]
      }
    ],
    "standard_headers" : null,
    "retry_policies" : [
      {
        "policy_id" : "linear",
        "title" : "Linear",
        "details" : "When a webhook is not received for whatever reason, MyAwesomeApp will continue trying to send the webhook once an hour for up to 3 days."
      }
    ],
    "authentication" : {
      "type" : "custom",
      "details" : null,
      "options" : [
        {
          "token" : {
            "properties" : [
              {
                "property" : "value",
                "name" : "App Key",
                "details" : "This is the app key from your account.",
                "required" : true,
                "request_from_user" : true
              },
              {
                "property" : "location",
                "value" : "header"
              },
              {
                "property" : "variable",
                "value" : "X-MyAwesomeApp-Token"
              }
            ]
          }
        }
      ]
    }
  },
  "responses" : {
    "details" : "To acknowledge that you received the webhook without any problem, your server should return a 200 HTTP status code. Any other information you return in the request headers or request body will be ignored. Any response code outside the 200 range, including 3xx codes, will indicate to MyAwesomeApp\n that you did not receive the webhook.",
    "codes" : {
      "success" : [
        "2xx"
      ],
      "failure" : [
        "3xx",
        "4xx",
        "5xx"
      ]
    }
  },
  "events" : {
    "details" : "",
    "key_location" : {
      "json" : {
        "location" : "payload",
        "variable" : "type"
      }
    },
    "options" : [
      {
        "title" : "Messages",
        "events" : [
          {
            "key" : "message.sent",
            "label" : "Message Sent",
            "details" : "Occurs whenever a message is sent to another MyAweomeApp user.",
            "payloads" : {
              "json" : {
                "message_id" : "847774749498498498498498",
                "from_user" : "168161",
                "to_user" : "2548744",
                "message" : "Oh yeah, I am going to be there for sure!",
                "type" : "message.sent"
              }
            }
          },
          {
            "key" : "message.deleted",
            "label" : "Message Deleted",
            "details" : "Occurs whenever a user deletes a message from their account.",
            "payloads" : {
              "json" : {
                "message_id" : "847774749498498498498498",
                "message" : "Oh yeah, I am going to be there for sure!",
                "type" : "message.deleted"
              }
            }
          }
        ]
      },
      {
        "title" : "Balance",
        "events" : [
          {
            "key" : "balance.available",
            "label" : "Balance Available",
            "details" : "Occurs whenever your MyAwesomeApp balance has been updated (e.g. when money is added or removed from the account).",
            "payloads" : {
              "json" : {
                "balance" : false,
                "type" : "balance.available",
                "user_id" : 168161
              }
            }
          },
          {
            "key" : "balance.low",
            "label" : "Balance Low",
            "details" : "Occurs whenever your MyAwesomeApp balance falls below $2.00.",
            "payloads" : {
              "json" : {
                "balance" : false,
                "type" : "balance.low",
                "user_id" : 168161
              }
            }
          }
        ]
      }
    ]
  },
  "example_cases" : [
    {
      "group_name" : "Example Message Sending",
      "cases" : [
        {
          "title" : "User sends a message and has a high account balance.",
          "overview" : "The user simply sends a message and they have enough money on the account so really there is no issue of them falling low and needing to readd funds.",
          "events" : [
            "message.sent",
            "balance.available"
          ]
        },
        {
          "title" : "User sends a message and the balance falls into the low category.",
          "overview" : "The user sends the message and then is alerted that their balance is getting low.",
          "events" : [
            "message.sent",
            "balance.available",
            "balance.low"
          ]
        }
      ]
    }
  ]
}
Getting Started