Webhooks Documentation
We wrote this document for webhook providers to copy and adapt to their own webhook delivery configuration. Most segments can be fully copied, a few others require you to select the option for your docs. Watch out for the tooltips and callouts.
What are webhooks?
Webhooks are a mechanism for notifying third-party applications about a change in their account in real time. Oftentimes, APIs are able to respond immediately to API calls, but not all the time, in scenarios like this, a webhook event is used to notify the third-party app via a Webhook URL.
Event Types
Retry Behaviour
Convoy supports two types of retry strategies: linear
, and exponential backoff
, based on your configuration you
can use any of the below to communicate with your users.
In production, if your endpoint does not respond with a 2xx,
we continue to retry the event every n seconds for a
maximum of n hours.
Webhook Verification
There are two ways you can verify webhooks from . Let’s take a look at both methods and what safe guards they provide.
Static IPs
With this verification method, you can configure your firewalls to receive webhooks from only the following IP addresses, while blocking out the rest.
18.219.210.243
3.146.152.80
Signature Verification
With this verification method, we’re able to determine if the webhook came from , and has not been tampered with in transit. We use Convoy, and they provide SDKs for the following languages:
Make sure to substitue the encoding
, hash
, and header
for your configuration.
Supported values for them are:
encoding
:hex
,base64
.hash
:SHA256
,SHA512
.header
: provider specific. E.g.X-Paystack-Signature
.
import (
"io"
"net/http"
convoy "github.com/frain-dev/convoy-go/v2"
)
func HandleWebhook(w http.ResponseWriter, r *http.Request) {
body, err := io.ReadAll(r.Body)
if err != nil {
w.WriteHeader(400)
}
webhook := convoy.NewWebhook(
convoy.WebhookOpts{
Hash: "SHA512",
Secret: os.Getenv("WEBHOOKS_ENDPOINT_SECRET"),
Payload: body,
Encoding: "hex",
SigHeader: "X-Convoy-Signature",
}
)
err = webhook.VerifyRequest(r)
if err != nil {
w.WriteHeader(400)
}
// write webhook to queue.
w.WriteHeader(200)
}
Consuming webhooks best practices.
- Always return early. If you have a long running process that you’d like to executed
preferably push that to a background job to process, and return quickly with a
2xx
. - Favour Idempotent processing. All webhooks are delivered with a
X-Convoy-Idempotency-Key
header which can be used for Idempotent processing. - Default to
HTTPS
endpoints. Webhooks are endpoint exposed to the internet, for safety, we default toHTTPS
only URLs, and validate the certs.
Was this page helpful?