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

{
    "event_type": "invoice.created",
    "data": {
        "id": "inv_3234aei32489aie2o3245",
        "status": "created"
    }
}

​

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.

• Linear Retry Strategy
• Exponential Backoff Strategy

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 provider. 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.

• US Cloud IPs
• EU Cloud IPs

18.219.210.243

​

Signature Verification

With this verification method, we’re able to determine if the webhook came from provider, and has not been tampered with in transit. We use Convoy, and they provide SDKs for the following languages:

• handler.go
• handler.js
• handler.rb

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.

1. 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.
2. Favour Idempotent processing. All webhooks are delivered with a X-Convoy-Idempotency-Key header which can be used for Idempotent processing.
3. Default to HTTPS endpoints. Webhooks are endpoint exposed to the internet, for safety, we default to HTTPS only URLs, and validate the certs.