SERV Alert EAPI

Our service supports the following two authentication mechanisms:

1. HMAC Signature

This mechanism uses a secret key to sign webhook requests, allowing the destination system to verify data integrity.

A secret key is shared between the webhook provider and SERV.

SERV uses this key and HMAC-SHA256 algorithm to generate a hash signature based on the webhook payload. The following is the Python code:

hmac.new(
    key=bytes(secret, "utf-8"),
    msg=payload, # bytes
    digestmod=hashlib.sha256,
).hexdigest()

The signature is included in the request header, named x-serv-signature, alongside the webhook request.

Upon receiving the request, the provider uses the same secret key and algorithm to compute a signature from the payload.

The computed signature is then compared to the one in the x-serv-signature header. If they match, the request is valid; if not, it is rejected.

2. Token(OAuth) authentication

This mechanism includes an authorisation token in the webhook request, obtained through an authentication request.

The webhook provider shares authentication details (such as the authentication endpoint, client ID/secret) with SERV.

SERV requests an access token from the authorisation server using these details.

The token is sent in the Authorization header of the webhook request, in the following format:

Authorization: Bearer {token}

Upon receiving the request, the webhook provider validates the token. If valid, the request is processed; if not, it is rejected.