Skip to main content
Webhooks allow you to be notified about interesting events occurring in your Tenants Decoda accounts in real-time. To start receiving events through a webhook, you must create a new Webhook for the Tenant you wish to subscribe to. All webhooks are authenticated using HMAC SHA-256 and their payloads are signed using a secret which is generated when you create a webhook endpoint.

​
Security

To validate that webhook payloads are legitimate, use the Decoda-Signature header. The Decoda-Signature header contains the HMAC SHA-256 signature of the payload and a secret key. Your server should generate it’s own signature using the same secret and compare it with the received signature. See the examples on the right for how to validate Decoda Signatures. 
import json
from fastapi import FastAPI, Request, HTTPException
import hmac
import hashlib

app = FastAPI()

# Secret key for signature validation, store this in a safe place!
SECRET = "961c2c1c9c66dad600f29a26e0320a96"

def generate_signature(body: str, secret: str) -> str:
    return hmac.new(secret.encode(), body.encode(), hashlib.sha256).hexdigest()

# Define a route to handle incoming webhooks.
@app.post("/webhook")
async def webhook(request: Request):
    data = await request.json()
    signature = request.headers.get("Decoda-Signature")
    expected_signature = generate_signature(json.dumps(data), SECRET)

    # Validate the signature
    if not hmac.compare_digest(signature, expected_signature):
        raise HTTPException(status_code=401, detail="Invalid signature")
    return {"status": "success"}

if __name__ == "__main__":
    import uvicorn
    uvicorn.run(app, host="0.0.0.0", port=8001)

​
Error Handling

If a webhook delivery fails, the system will retry the delivery. If the delivery continues to fail, an email notification will be sent to the notification_email specified in the webhook. To prevent this, you can set the notification_email to null when creating the webhook.