Please see the full REST API documentation for API implementation details.

Resource: REST Hooks

REST hooks provide a way for API callers to dynamically configure callback requests for events they would like to be notified about. Examples include receiving a notification when a meeting is scheduled or when an action item is created.

The Lucid Meetings REST Hook mechanism follows the patterns described by Zapier for their Notification REST Hooks and by resthooks.org for "Skinny Payloads." With skinny payloads we deliver (POST) a notification that an event has occurred, along with a URL for the affected resource. To access the full resource, the recipient must retrieve (GET) the resource via normal, authenticated API calls.


Properties

#
Field Type Notes
hook_id integer
token_id integer Identifies the API token used to create the hook
organization_id tuple associated organization: {organization_id, name}
room_id tuple associated room: {room_id, name}
event tuple trigger event: {event, description}
target_url URL The target URL for the notification callback
create_ts timestamp
update_ts timestamp

My Hooks

#
GET /lucid/api/v1/hooks (must be logged in)
Query parameter Notes
fields See Field Filtering
envelope See Enveloping

Sample Request

GET /lucid/api/v1/hooks?fields=hook_id,room_id,event
Content-Type: application/json; charset=utf-8
Content-Length: 653
X-Rate-Limit-Limit: 100
X-Rate-Limit-Remaining: 98
X-Rate-Limit-Reset: 60
X-Rate-Limit-Used: 2
X-Requestor: jtkeith@lucidmeetings.com
[
  {
    "hook_id": 10,
    "room_id": {
      "value": 74,
      "display": "Engineering Team"
    },
    "event": {
      "value": "meeting_scheduled",
      "display": "Meeting scheduled in a room"
    }
  },
  {
    "hook_id": 12,
    "room_id": {
      "value": 74,
      "display": "Engineering Team"
    },
    "event": {
      "value": "meeting_ended",
      "display": "Meeting session ended in a room"
    }
  }
]

Getting a Single Hook

#
GET /lucid/api/v1/hooks/:hook_id
Query parameter Notes
fields See Field Filtering
envelope See Enveloping

Sample Request

GET /lucid/api/v1/hooks/10
Content-Type: application/json; charset=utf-8 
Content-Length: 813
X-Requestor: jtkeith@lucidmeetings.com
X-Rate-Limit-Limit: 100
X-Rate-Limit-Remaining: 99
X-Rate-Limit-Used: 1
X-Rate-Limit-Reset: 60
{
  "id": 10,
  "hook_id": 10,
  "organization_id": null,
  "room_id": {
    "value": 74,
    "display": "Engineering Team"
  },
  "target_url": "https:\/\/zapier.com\/hooks\/standard\/286082\/e139ef7fb5174f42953716e966621fc0\/",
  "event": {
    "value": "meeting_scheduled",
    "display": "Meeting scheduled in a room"
  },
  "create_ts": {
    "value": 1463464721,
    "iso_8601": "2016-05-17T05:58:41Z"
  },
  "update_ts": {
    "value": 1463464721,
    "iso_8601": "2016-05-17T05:58:41Z"
  }
}

Creating a Hook

#
POST /lucid/api/v1/hooks
Field Required Notes
organization_id no The organization associated with the event, if any
room_id no The room associated with the event, if any
event yes The event to monitor
target_url yes The URL to callback when the event occurs

Sample Request

POST /lucid/api/v1/hooks
Content-Type: application/json
{
  "event" : "meeting_scheduled",
  "target_url" : "http:\/\/example.com\/api\/events",
  "room_id" : 74
}
201 Created
Location: https://site.lucidmeetings.com/lucid/api/v1/hooks/18
Content-Type: application/json
{
  "id": 18,
  "hook_id": 18,
  "organization_id": null,
  "room_id": {
    "value": 74,
    "display": "Engineering Team"
  },
  "target_url": "http:\/\/example.com\/api\/events",
  "event": {
    "value": "meeting_scheduled",
    "display": "Meeting scheduled in a room"
  },
  "create_ts": {
    "value": 1463540109,
    "iso_8601": "2016-05-18T02:55:09Z"
  },
  "update_ts": {
    "value": 1463540109,
    "iso_8601": "2016-05-18T02:55:09Z"
  }
}

Deleting a Hook

#
DELETE /lucid/api/v1/hooks/:hook_id

Sample Request

DELETE /lucid/api/v1/hooks/10


204 No Content


Sending a Hook

#

When the Lucid Meetings service matches an event to a hook subscription, we POST event data to the target_url supplied when the hook was created.

POST data Notes
resource_url The URL for the resource associated with the event
event Hook data: event field
organization_id Hook data: organization_id field
room_id Hook data: room_id field
hook_id Hook data: the resource identifier for this hook

If the target_url responds with a 410 Gone status code we immediately remove the subscription to the failing hook (unsubscribe). Additionally, excessive failures (multiple 4xx or 5xx failures) logged and eventually unsubscribed as well.

POST target_url
Content-Type: application/json
{
  "resource_url" : "resource_url",
  "event" : "event",
  "organization_id" : organization_id,
  "room_id" : room_id,
  "hook_id" : hook_id
}

Sample Request

POST https://zapier.com/hooks/standard/286082/e139ef7fb5174f42953716e966621fc0/
Content-Type: application/json
{
  "resource_url" : "https://site.lucidmeetings.com/meetings/1489",
  "event" : "meeting_scheduled",
  "organization_id" : null,
  "room_id" : 74,
  "hook_id" : 18
}