Webhooks

After creating an Imagen application, you will be able to create webhooks for your application. Webhooks are HTTP callbacks sent from Imagen that are tied to events that your application is interested in.

As an example, a webhook can be set up to send an event to your callback URL every time an Imagen record (created by a user of your application) is updated.

Creating a webhook

1. Go to the Your Applications page in ImagenWeb’s Developers section and click the Edit link in the context menu of the application. On the Edit application page, browse through to the Webhooks tab and click the Create webhook link.

2. Fill out the Create a webhook form.

   Creating a valid Callback URL

   • On attempting to create a webhook, your callback URL must respond with an HTTP status code of 200. If it does not, your webhook will not be created.

   • Your callback URL must also echo back (as part of the response body) a variable sent by ImagenWeb as a query string parameter (named challenge) to your callback URL i.e.

https://[Your_Imagen-Domain]:83/event?challenge=echoThisStringBack. 

This validation rule is triggered by clicking the Create button.

Receiving a webhook

• An Imagen event will be sent as an HTTP POST request to your webhook’s callback URL with a request body that is formatted in XML (note the example webhook body.)

• Webhook events are batched into as few HTTP requests as possible. For example, if you create 1000 records in a minute, Imagen won’t spawn 1000 separate HTTP requests to your webhook’s Callback URL. At the same time, the webhook’s POST body has a sensible file size limit too, which is to say, Imagen won’t be sending you one massive webhook event either.

• If your webhook’s Callback URL responds to an Imagen event with an HTTP status code between 200 to 299, Imagen will assume the webhook has been received and will stop sending it. Any other HTTP status code and Imagen will retry 3 times, on an exponentially increasing delay, before giving up.

• Every Imagen event has its own unique ID, which can be used to avoid processing duplicates.

• Imagen events are also signed so that applications can verify that the requests they are receiving are in fact from Imagen. The signature is sent within an HTTP header called X-Imagen-Webhook, the value of which is a base64 digest of an HMAC-SHA256 hash. The hashed content is a concatenation of the Callback URL (exactly as it was provided during the webhook’s creation) and the full request body. The key used to sign this text is your application’s secret access key.

Example X-Imagen-Webhook

X-Imagen-Webhook:HMAC-SHA256 dNWKTKPJtOuApSMbycwZLrwEIMrAzpLKL+JoHwDsJZE=

Example webhook body

<?xml version="1.0" encoding="UTF-8"?>
<ImagenNotification>
    <Events>
        <Event ID="D42DDB78-16DB-43cf-9E42-BB95567A1867"
               Name="record"
               Operation="CREATE">
            <AccessToken>69d104e96966d1fa96a7d6c044ec6423758c6be6</AccessToken>
            <ChangedBy>user@example.com</ChangedBy>
            <DateOccurred>2015-05-28T16:02:34Z</DateOccurred>
            <Data>
                <ImagenRecord id="10059">
                    <Fields>
                        <Published Type="DateTime">2015-05-28 16:02:26</Published>
                        <Title Type="Text">My record title</Title>
                        <guid Type="GUID">46BE1D68-2CE3-456a-BF0E-ADA2901EDD67</guid>
                    </Fields>
                </ImagenRecord>
            </Data>
        </Event>
    </Events>
</ImagenNotification>

I’m not receiving webhooks...

If a user of your application creates a record and there’s a webhook tied to the relevant Imagen event, your webhook will be processed and an event will be sent to the webhook’s callback URL. However, if that same user updates a record created by someone else that hasn’t authorized your application, the webhook won’t be processed.

Always remember that your application’s webhooks are tied to the users that have authorised your application.