Webhooks

Introduction

Welcome to the Gaggle Mail Webhooks documentation! Webhooks provide a modern, responsive way to get real-time notifications about events happening in your groups. They work alongside our API to keep you informed instantly.

Where to Register Webhooks

To register a webhook, head over to your Profile page and open the Developer Tools section. There, you’ll find a “Webhooks” tab. You can give each webhook a name, specify the endpoint URL, and then click “Create.”

Where to Subscribe to Events

Once your webhook is registered, you’ll need to subscribe to specific events. You can do this for each group on its Notifications page. Once you have your webhook registered, as well as being able to opt into notifications by Email or Email Digest, you will also be able to select webhook notifications.

How to Handle Webhook Calls

You can find full documentation on all webhook events and payloads in the Webhooks section of our API Reference.

Validation and Signatures

Every webhook payload is accompanied by a secure hash signature in the X-Signature header. This signature is created using a secret key generated when you set up the webhook. To validate the request, make a SHA-256 hash of the incoming payload with the secret key and ensure it matches the provided signature.

For reference, here's how we generate the signature in Python:

def sign_payload(payload: dict, secret: str) -> str:
    if not secret:
        return None

    """Sign a payload with the secret."""
    return hmac.new(secret.encode(), json.dumps(payload).encode(), hashlib.sha256).hexdigest()

Where to View Logs

To view logs for each webhook, return to the Developer Tools section of your Profile page. For each registered webhook, there’s a “View Logs” button. Clicking it will show you all request and response logs for the last seven days, including success status and payload details.

Feedback

We’re continually improving our webhook system, and your input is invaluable. If you need additional webhook events, changes to existing payloads, or have any suggestions or general feedback, we’d love to hear from you. Please don’t hesitate to get in touch and let us know how we can make webhooks work even better for you.