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.
Was this page helpful to you? Feel free to reach out via support@ohdear.app or on Twitter via @OhDearApp if you have any other questions. We'd love to help!