Webhook Requirements

At Grip we believe that the best, most real-time and robust integrations are through webhooks. It allows for the data provider (registration system, exhibition management platform, website CMS) to have the greatest control over keeping Grip in-sync with their internal data.

Outbound Webhooks

Outbound webhooks (from Grip's perspective) allow Grip to notify your systems when a change event takes place in Grip. For outbound webhooks, we invite you to configure these programmatically through our API service.

Inbound Webhooks

Inbound webhooks allows you to inform us of specific changes that have occurred on your system. For example, for when a ticket holder's profile has been updated, or when a new event session was created and so on.

Setting Up

To set up an inbound webhook, you will need to tell us the following:

  1. Which container id you are setting up for.
  2. Decide what you wish to affect on Grip when this webhook is triggered. Presently, the following webhook events are supported:
    1. Create Thing
    2. Update Thing
    3. Delete Thing
  3. Tell us where in your webhook message we should look for finding out what webhook event it is. We can look in either the HTTP Headers or the Body element.
  4. Tell us what the identifier in (3) is, for example, if you might be want to use the HTTP Header reg-event-id to be your identifier.
  5. Tell us what the value of the identifier in (4) is, for example, you want us to only take action if your reg-event-id header's value to be new_ticket.
  6. Tell us how we can authenticate the webhook messages received. I.e. How we can be sure that the notification came from you and no one else? We can do this by either one of the following means:
    1. Whitelist IP addresses.
    2. HTTP header or body value checking. If you opt for value checking, then you need to tell us if we should perform either a simple value comparison or a digest signature check against a shared secret. Again, we will need to know both the authentication identifier name and expected value or shared secret to do this. For digest signature checks, we can only support HMAC-sha256.

In summary, provide us with the following information per webhook event per container based on the setup you have (and need):

Information Required
IP Whitelist Simple Signature Authentication
Digest Signature Check
Container ID
Yes Yes Yes
Webhook Event
(Create Thing, Update Thing, or Delete Thing)
Yes Yes Yes
Webhook Event Identifier Location
(Header or Body)
Yes Yes Yes
Webhook Event Identifier Field
Yes Yes Yes
Webhook Event Identifier Field Value
Yes Yes Yes
Authentication Method
(IP, Simple value comparison, or digest signature)
Yes Yes Yes
Authentication Identifier Location
(Header or Body)
No Yes Yes
Authentication Identifier Field
No Yes Yes
Authentication Identifier Field Value
(List of IP addresses or Value)
Yes Yes No
Authentication Identifier Shared Secret
No No Yes

Triggering A Webhook Event

After your webhook is configured, you will then be able to trigger them by issuing a HTTP POST request to our API service's at https:// HOST>/<API VERSION>/webhook/container/<CONTAINER_ID> . Triggers should only be made with JSON payloads in the HTTP POST body and should conform to the above settings.

For example, if you have the following webhook configured

  • Container ID: 123
  • Webhook Event: Create Thing
  • Webhook Event Identifer: Header
  • Webhook Event Identifier Field: X-Reg-Event
  • Webhook Event Identifier Field Value: new_registration
  • Authentication Method: digest signature
  • Authentication Identifier Location: Body
  • Authentication Identifier Field: registration-signature
  • Authentication Identifier Shared Secret: some_shared_secret_key

Then we expect that your HTTP POST requests should look like this:

POST /1/webhook/container/123
Authorization: <Your Grip Token>
Content-Type: application/json
X-Reg-Event: new_registration
{
   "name": "John Doe",
   "registration_id": "abc-123",
   // other key value pairs follow
   "registration-signature": "aanVaf12fnvK974ds3cZnIa1vc"
}

Still need help? Contact Us Contact Us