Podio API Documentation

Hooks

Hooks are webhooks that can call external sites when certain actions occur in Podio. Hooks needs to be verified before they become active. Verification occurs by the external URL being called with a code, which the external site must then use to activate the hook.

The following hooks are currently supported:

Apps

App level hooks are events specific to an app. When creating these hooks use "app" as the ref_type and the app_id as the ref_id. Additionally, the three hooks item.create, item.update and item.delete can also work on a field level. If you use "app_field" as the ref_type and an app field_id as the ref_id your hook will only be triggered if the changes happen to that particular field.

  • item.create: When a new item is created. Provides parameter "item_id", "item_revision_id" and "external_id".
  • item.update: When an item is updated. Provides parameter "item_id", "item_revision_id" and "external_id".
  • item.delete: When an item is deleted. Provides parameter "item_id", "item_revision_id" and "external_id".
  • comment.create: When a comment is added to an item. Provides parameters "item_id" and "comment_id".
  • comment.delete: When a comment is deleted on an item. Provides parameters "item_id" and "comment_id".
  • file.change: When attachments on an item change, ie. added, replaced or removed. Provides parameter "item_id", "action_type" and "file_ids". Possible values of parameter "action_type" are: "file_created" or "file_replaced" or "file_deleted". Parameter "file_ids" is a comma delimited string of file id(s).
  • app.update: When the app is updated. Provides parameter "app_id".
  • app.delete: When the app is deleted. Provides parameter "app_id".
  • form.create: When a webform is created on the app. Provides parameter "form_id" and "app_id".
  • form.update: When a webform is updated, disabled or enabled on the app. Provides parameter "form_id" and "app_id".
  • form.delete: When a webform is deleted on the app. Provides parameter "form_id" and "app_id".
  • tag.add: When a tag has been assigned to an item. Provides parameter "item_id" and "target_type".
  • tag.delete: When a tag has been removed for an item. Provides parameter "item_id" and "target_type"

Spaces

Space level hooks are events that are specific to a space, but not a specific app. Currently that covers public tasks in the space and members joining and leaving. When creating these hooks use "space" as the ref_type and the space_id as the ref_id.

  • app.create: When a new app is created on the space. Provides parameter "app_id".
  • task.create: When a shared task is created on the space. Provides parameter "task_id".
  • task.update: When a shared task is updated on the space. Provides parameter "task_id".
  • task.delete: When a shared task is deleted on the space. Provides parameter "task_id".
  • member.add: When a member is added to the space. Provides parameters "space_id" and "user_id".
  • member.remove: When a member is removed from the space. Provides parameters "space_id" and "user_id".
  • (deprecated) contact.create: When a new space contact is created on the space. Provides parameter "profile_id".
  • (deprecated) contact.update: When a space contact is updated on the space. Provides parameter "profile_id".
  • (deprecated) contact.delete: When a space contact is deleted on the space. Provides parameter "profile_id".
  • status.create: When a new status is created on the space. Provides parameter "status_id".
  • status.update: When a status is updated on the space. Provides parameter "status_id".
  • status.delete: When a status is deleted on the space. Provides parameter "status_id".

Hooks

Hook level hooks are currently only used for verification when you create new webhooks.

  • hook.verify: When verification is requested for the hook. The verification code is passed in the "code" parameter.

When one of the subscribed events occur, the URL is called with some additional parameters. The "type" parameter is always set to the type of event. In addition another parameter will normally be set given more information about the event. For the item events above the parameter "item_id" will give the id of the item that was created, updated or deleted.

When the hook is verified a call is made with the "type" parameter set to "hook.verify" and the "code" parameter set to the code required to validate the hook. Use this code in the call to verify the hook. Only after verification will the hook be called on events.

The hook must respond with a 2xx status code. If the status code is different from 2xx more than 50 consecutive times the hook will return to being unverified and will have to be verified again to be active. Additionally, your hook may return to unverified if you do not send responses in a timely manner (15 seconds). You should handle any heavy processing asynchronously.

Only hooks on port 80 and 443 are supported, i.e. you cannot use "http://www.mydomain.com/podio/hook:8080", only "http://www.mydomain.com/podio/hook" or "https://www.mydomain.com/podio/hook".