Getting started with Oh Dear webhooks

Let's start by enabling webhooks and pointing them to your own endpoint.

Enable webhooks in your account

Navigate to the notification settings page, scroll down to the webhooks section and add your webhook URL.

Once your webhook is configured, we'll call it for every event we fire. You get the raw payload and can act on it as you see fit.

How the webhooks work

Every event we fire internally, will also be translated to the webhook URL you provide in your team settings page in the account.

This means you can receive the raw payload of events like site up/down, certificate changes, ... you name it. You can then use that information to update internal systems, escalate alerts, log events, etc.

Our webhook works by firing a POST request to the endpoint you specified. All data related to the event that just took place will be inside the POST payload. For specific examples of each payload, have a look at the different webhook events.

Authentication

All webhooks we send will be signed by a signing secret, unique to your team. You can find the signing secret in your account in the team settings.

It'll be displayed as Web hook signing secret: YoUrSeCreT.

You don't have to validate the incoming request, but it's highly suggested.

Webhook retries

If we receive an HTTP/200 from your webhook URL, we consider the webhook successful. If your application returns anything else, including 301 or 302 redirects, we mark the webhook as failed and will resend the same payload again.

We will try to send the webhook up to 3 times. If we receive a non-HTTP/200 response code, or a timeout (of 3 seconds or more) for 3 times, we consider the webhook failed and will not resend that particular event.

We do not disable webhooks because they failed a couple of times, we'll only disable them if you remove the URL from your account page.

Webhook authentication & signing

Our signing method is simple but efficient. For every webhook we call, we pass an additional header called OhDear-Signature that contains the hash of the payload.

In your webhook, you can validate if that OhDear-Signature header contains the hash you expected.

It's calculated like this:

$computedSignature = hash_hmac('sha256', $payload, $secret);

The $payload is the body of the POST request, which will be a JSON representation of the event.

The $secret is the one you can find on your team notifications settings page

The hash_hmac() function is a PHP function that generates a keyed hash value using the HMAC method.

The $computedSignature should match the Ohdear-Signature that's been set. If you use our laravel package, the signature checking is handled automatically.