Tutorials

Working with Webhooks

Webhooks provide a way to build event-driven apps, because you can be notified about changes in Podio. Webhooks allow a URL to be called when an item is created, updated or deleted in an app.

Example scenario

Imagine that a developer would like to be notified by SMS of new bugs created in their Podio bug tracker. Since Podio doesn't support sending of SMS messages, this would have to be implemented using a third-party SMS gateway service. Instead of polling for new bugs every 5 minutes, a webhook can be set up on the bugs app that will call the SMS service whenever a bug is created. This allows for near real-time notifications and avoids the need to continually check for changes in Podio.

Supported events

Each webhook is registered to receive updates about a specific event in Podio, for example an item being updated or a comment being added. View a full list of supported events in the API reference documentation.

Registering your webhook

The easiest way to register a webhook is from inside Podio. Go to your app and click on 'Developer' in the settings dropdown. Here you can add new webhooks and see a list of existing webhooks for that app.

If you need to fully automate creation of webhooks you can also create new webhooks programatically using the create hook operation.

Notice: You can have up to 10 webhooks of each type (create, update, delete etc.) of each item, app, comment etc.

Only hooks on port 80 and 443 are supported, i.e. you cannot use "http://example.com.com/podio/hook:8080", only "http://example.com.com/podio/hook" or "https://example.com.com/podio/hook". Any query string parameters in your URL will be included in the body of hook invocations. They will not be preserved. I.e. if your hook is https://example.com.com/podio/hook?foo=bar Podio will make requests to https://example.com.com/podio/hook but foo=bar will be included in the HTTP body of the request.

Verifying webhooks

Before your webhooks becomes active the URL must be verified. Immediately after the webhooks is created a hook.verify notification is sent to the URL endpoint. The endpoint must then return the code to the validation operation. Events will only be sent to the endpoint after a completed verification.

Invocation

Webhooks are notified by a POST to the URL registered a long with one or more parameters. The type parameter gives the type of event as outlined above and will always be present. In addition, other parameters can be added depending on the type of event. See the section above for details. Any existing parameters on the URL will be retained.

Avoiding infinite loops

Often you want to update the item that caused the hook to fire. For example immediately update a field value when some other field value changes. That can cause infinite loops where your update causes yet another hook to fire.

To avoid this situation the add new item, update item and delete item operations all support a hook query parameter you can use to prevent hooks from firing as you manipulate items using these operations.

Debugging webhooks

Since webhooks require a publicly accessible URL to function they can be hard to test from your local machine. You can use services like RequestBin to expose your local webservice on the public internet.

Example code

The example code below shows a simple switch statement that will react to all Podio webhooks. It will also validate any webhooks it's asked to verify.

php ruby


case params['type']
  when 'hook.verify'
    # Validate the webhook
    Podio::Hook.validate(params['hook_id'], params['code'])
  when 'item.create'
    # Do something. item_id is available in params['item_id']
  when 'item.update'
    # Do something. item_id is available in params['item_id']
  when 'item.delete'
    # Do something. item_id is available in params['item_id']
end


switch ($_POST['type']) {
  case 'hook.verify':
    // Validate the webhook
    PodioHook::validate($_POST['hook_id'], array('code' => $_POST['code']));
  case 'item.create':
    // Do something. item_id is available in $_POST['item_id']
  case 'item.update':
    // Do something. item_id is available in $_POST['item_id']
  case 'item.delete':
    // Do something. item_id is available in $_POST['item_id']
}

Why isn't my webhook being called?

First, make sure you have verified your webhook, and that the url for the webhook is still publically available for our server to call.

Then, make sure the url we call can handle the load and always returns a successful 2xx HTTP response within 15 seconds. We often see that people make many time consuming calls we invoke the webhook, going beyond the 15 seconds we wait for a successful response.

If a call to a webhook fails - is not accessible or does not respond with a 2xx within 15 seconds - more than 15 times within 15 minutes, that specific webhook gets suspended for 15 minutes. All actions that would have invoked the webhook within these 15 minutes are ignored.

If a call to a webhook fails more than 200 times within 7 days, the hook is permanently disabled and will have to enabled again by verifying the webhook.

Call to web hooks are put on our low priority queue, meaning that they will usually be invoked immedidately, but in peak times there can be a delay of a few seconds or even minutes. On very rare occasions a webhook call can be delayed as much as 30 minutes, but as long the webhook is active, it will always be invoked for all actions sooner or later.