In order to establish a solid communication through webhooks, both the publishers and the consumers have to respect their responsibilities.  This blog post touches upon the responsibilities of the webhook publisher.

Reliability

As a webhook publisher, you cannot assume continuously stable network connectivity or a consumer with a 100% guaranteed uptime.  Therefore, it’s important to send out the webhooks in an asynchronous fashion and not inline into the process.  An asynchronous implementation must foresee a decent level of automatic retry policies, preferably with an exponential back off.  One could implement a fall-back protocol (e.g. a queue), in case the webhook delivery fails.  Enabling notifications on failure is also helpful, to alert the webhook consumer through different communication channels.

Security

Needless to say that all communication must go through encrypted channels, so via HTTPS.  Next to that, it’s a responsibility to give the webhook consumer a way to identify that the event originates from your system.  A really good and simple approach to this, is allowing the webhook consumer to provide a shared secret during webhook registration.  That secret is used by the webhook publisher to compute hash-based message authentication code, which is added to the HTTP headers.  This gives the consumer the ability to verify the authenticity of the message and to validate message integrity.  A good example can be found here.

Endpoint validation

At the moment of webhook registration, it’s important to validate whether you can access the HTTP endpoint.  If not, it’s  advised to return a clear error message to the webhook consumer.  Once the registration is successful, one could continuously validate the availability of the consumer.  This could be done by implementing some kind of heartbeat functionality, every x minutes.  In case of unavailability, you can fire notifications to inform the webhook consumer or even unregister the consumer after a long period of inactivity.  In case you implement such a heartbeat, it’s important to clearly document this, so the webhook consumer knows what to expect.

These are the main responsibilities you have as a webhook publisher.  If you can provide visibility on top of that, you really drive fast adoption of your webhooks.

Cheers!
Toon