Webhooks are a really useful way of systems calling back to a website you control when certain actions have taken place. A Webhook is simply an HTTP POST to a URL you specify. The body of the request is in JSON format. You can then take whatever action you require. For example, an advanced use-case may be that when an instance is created, a callback to a system you control adds the instance into a load balancing pool or DNS entry.
How to setup a webhook
Click on your account name in the top right corner or click on Settings in the left hand bar, then click on "Webhooks". You'll see a page like this:
Then you can click the + Create webhook button. Here you enter the URL of the webhook and choose the events you want to be notified of. These should be self-explanatory and you can select more than one (or the magical All events option to be told about everything). After you've finished the selection, you click Create webhook to save the webhook.
At this point if you wish, you can click the lightning bolt icon alongside the webhook to send a test event (with dummy data) to the webhook to check everything is OK.
Requirements for webhooks
The webhook response must be returned within 5 seconds of the request being made. The HTTP response for the request must be a 2xx status. If the request times out or receives a 3xx/4xx/5xx status then the request will be resent at increasing intervals (after 5 minutes, a further 30 minutes, 1 hour, 2 hours and then finally after 6 hours). After the final request has been made, if it's still failing then the webhook will be disabled. To re-enable the webhook simply edit it and click Update webhook and we'll reset it to enabled again.
When a webhook request is made, there will be an X-Civo-Event header sent containing a UUID. If the event needs retrying the same header value will be sent. This will enable you to ensure the same event isn't processed multiple times (if your handler isn't idempotent).
Validating the webhook is from Civo
When you create a webhook, a random secret is created. All requests sent to your webhook handler will have an X-Civo-Signatureheader containing a SHA1 HMAC hex digest of the request, using the secret as the key. For example, you could validate this value using some Ruby code like this (other languages will have something similar):
signature = OpenSSL::HMAC.hexdigest(
OpenSSL::Digest.new('sha1'),
MY_SECRET,
request.body
)
Sending email with webhooks
As an example of how to use webhooks, we'll use a third party service, Zapier, to create a webhook to email gateway. First signup for a free account at https://zapier.com. Then go to https://zapier.com/zapbook/email/webhook/ and click the "Turn Webhooks Into Sent Emails" Zap. When you get the URL from Zapier, you can create a new webhook with it in Civo.com and click the lightning bolt icon on the webhook listing to test it. Then go back to Zapier and click their "OK, I did this" button.
Then you can continue with Zapier's setup to type the recipient's email address and use the multi-line-with-a-plus icon to insert data from the webhook's JSON. In this case I've used the Payload Hostname.
This wil now send an email every time Civo.com sends an email to Zapier:
