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.

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 localtunnel or ProxyLocal 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