Rest Hook Documentation

What are REST Hooks?

REST Hooks itself is not a specification, it is a collection of patterns that treat webhooks like subscriptions. These subscriptions are manipulated via a REST API just like any other resource.

With most modern REST APIs, polling is the only way to detect changes. But it doesn’t have to be. On average, 98.5% of polls are wasted. There is a better way. REST Hooks enable real-time communication and eliminate polling.

— RESTHooks.org

Keap offers a growing set of REST Hooks to keep you notified of changes in your data. To get started, please visit our Interactive REST API Docs.

Hook Event Policy

After you’ve read the Interactive REST API Docs, you might be interested in the Event and Retry policies.

• Hook Events are sent only if the subscription is Verified.
• Hook Events are batched.
• Hook Events are attempted four times.
  • First: for most event types: occurs between 30 and 60 seconds of the originating system change. For contactGroup.applied and contactGroup.delete the interval is 5-10 minutes.
  • Second: occurs between 30 and 60 seconds, following the prior failed attempt.
  • Third: occurs after five minutes, following the prior failed attempt.
  • Fourth: occurs after 30 minutes, following the prior failed attempt.
• The second through fourth attempts will occur if your Hook Event receiver:
  • Does not respond within 30 seconds, or
  • Responds with a status code <200 or >=400 (but not 410).
• If the fourth attempt fails the subscription is marked Inactive until such time it is reactivated though a call to the /verify endpoint.
• If, at any time, your Hook Event receiver responds with status code 410, the subscription is considered Inactive.

REST Hook Event Payload

Each event will contain one or more changed objects of the same event type. The payload will contain a maximum of 1000 changed objects.

{
 "event_key": "<HOOK EVENT KEY IS HERE>",
 "object_type": "<RESOURCE NAME HERE>",
 "object_keys": [
   {
   "id": <RESOURCE OBJECT ID>,
   "apiUrl": "<REST API URL FOR RESOURCE MAY BE PRESENT>",
   "timestamp": "<EVENT TIMESTAMP>"
   },
   {
   "id": <RESOURCE OBJECT ID>,
   "apiUrl": "<REST API URL FOR RESOURCE MAY BE PRESENT>",
   "timestamp": "<EVENT TIMESTAMP>"
   },
   …
  ]
}