Webhooks

1
{
2
  "mcpServers": {
3
    "respan-docs": {
4
      "url": "https://mcp.respan.ai/mcp/docs"
5
    }
6
  }
7
}

The Respan platform provides a webhook system that allows you to receive notifications when certain events occur.

For example, when Respan logs a new request, your webhook and point can receive this notification as an API call from Respan.

Authentication

Respan uses digital signature strategy for webhook data verification.

The data sent from Respan undergoes the following process before you can use it:

1. The data is ready in Respan’s backend

1
{
2
    "some":"data"
3
}

2. The Respan encodes the data with your API Key string retrieved from the action’s header (we don’t store your API key) that triggers the webhook, using SHA-256 algorithm.

1
import hmac
2
import json
3
api_key = retrieve_from_header(some_action_header)
4
stringified_body = json.dumps(data_to_send)
5
signature = hmac.new(
6
    fake_api_key.encode(),
7
    stringified_body.encode(),
8
    "sha256"
9
).hexdigest()

3. The signature is then passed to X-Respan-Signature. This is case sensitive.

1
// Some header
2
{
3
    "X-Respan-Signature": "2217632f28bdfc939977d00790f1c8cc9997c23ab36de810ae7e4fecdb310603"
4
}

4. You can verify then data and accept or reject the payload

1
secret_key = YOUR_RESPAN_API_KEY
2
signature = request.headers.get("x-respan-signature")
3
compare_signature = hmac.new(secret_key.encode(), msg=stringify_data.encode(), digestmod="sha256").hexdigest()
4
5
if compare_signature != signature:
6
    return Response({"message": "Webhook signature does not match."}, status=401)

Using Webhook Secrets

Instead of using your API key for webhook signature verification, you can use a dedicated webhook secret. This provides better security by allowing you to use a separate secret specifically for webhook validation without exposing your API key.

When creating or editing a webhook in the Respan platform, you can copy the webhook secret and use it for signing the signature instead of using the API key.

To use the webhook secret, simply replace YOUR_RESPAN_API_KEY with your webhook secret in the verification code:

1
secret_key = YOUR_WEBHOOK_SECRET  # Use webhook secret instead of API key
2
signature = request.headers.get("x-respan-signature")
3
compare_signature = hmac.new(secret_key.encode(), msg=stringify_data.encode(), digestmod="sha256").hexdigest()
4
5
if compare_signature != signature:
6
    return Response({"message": "Webhook signature does not match."}, status=401)

Example for using Webhooks

1. Define a webhook endpoint in your application.

This endpoint sends an email to the admin when a webhook event is received.

1
import hmac
2
## This endpoint corresponds to http://localhost:8000/api/webhook/
3
## Replace this endpoint with your actual endpoint
4
class TestWebhook(APIView):
5
    authentication_classes = []
6
    permission_classes = [AllowAny]
7
    
8
    def post(self, request, *args, **kwargs):
9
        data = request.data
10
        stringify_data = json.dumps(data)
11
        secret_key = os.getenv("RESPAN_API_KEY")
12
        signature = request.headers.get("x-respan-signature")
13
        compare_signature = hmac.new(secret_key.encode(), msg=stringify_data.encode(), digestmod="sha256").hexdigest()
14
        
15
        if compare_signature != signature:
16
            return Response({"message": "Webhook signature does not match."}, status=401)
17
        
18
        send_mail(
19
            subject=f'Test Webhook Received',
20
            message=f"Webhook data: {data}",
21
            from_email=settings.DEFAULT_FROM_EMAIL,
22
            recipient_list=[settings.DEFAULT_FROM_EMAIL],
23
        )
24
        return Response({"message": "Webhook received."}, status=200)

2. Create a new webhook in the Respan platform.

   1. Go to the Webhooks page in the Respan platform.
   2. Click on the “Create Webhook” button, a modal will appear.
   
   3. Define the webhook URL. In this demo, it is http://localhost:8000/api/webhook/.
   4. Define the event type that triggers the webhook. In this demo, it is New request log (when an API call is logged).
   5. Define the API Key you want to associate this webhook with. In this demo, it is an admin development key.
   6. (Optional) Copy the webhook secret from the webhook settings if you want to use it instead of the API key for signature verification.
   7. Click on the “Create” button.

3. Make an API call to the chat completion endpoint

4. Receive the email.