Skip to main content

Webhooks

Webhooks allow you to receive real-time notifications when events occur in your pey account. Instead of polling our API for updates, webhooks push data to your server as events happen.

Authentication​

We use Standard Webhooks to sign all requests. This ensures that you can verify the authenticity of incoming webhooks and trust that they originated from pey.

To validate webhook signatures, we recommend using the official Standard Webhooks SDKs available for multiple programming languages.

Validation Example​

Here is a Python example using AWS Lambda triggered by AWS API Gateway.

import json
from standardwebhooks.webhooks import Webhook


def handler(event, context):
    try:
        headers = event.get('headers', {})
        webhook_id = headers.get('webhook-id', None) # TODO: This is the idempotency key, you can use it to deduplicate requests
        body = json.loads(event['body'])
    except Exception as e:
        print(f'Error parsing request info: {str(e)}')
        return { "statusCode": 400, "body": json.dumps({"message": f"Error parsing request info: {str(e)}"}) }    

    try:
        webhook_secret = "whsec_123456789" # TODO: Don't hardcode your secret, get it from an environment variable or secret manager
        wh = Webhook(webhook_secret) # Initialize the webhook validator with your secret
        wh.verify(event['body'], headers)  # Pass raw string, not parsed body

        print(f"Webhook validated successfully: {webhook_id}")
        return { "statusCode": 200 }
    except Exception as e:
        print(f"Error validating webhook: {e}")
        return { "statusCode": 500, "body": json.dumps({"message": f"Error validating webhook: {e}"}) }

Webhook delivery history​

You can view the delivery history of your webhooks in the "Settings" > "Developer" section. Click on the gear icon for the API key and then on the "Webhook Logs" button.

You will see all the webhook delivery attempts that have been made to your endpoint, the payload we sent, the response we received from your endpoint, and other relevant information.

Current Limitations​

warning

The following features are currently unavailable but will be added to our infrastructure before February 2026.

Retry Infrastructure​

We currently do not have automatic retry infrastructure for failed webhook deliveries. If your endpoint is unavailable or returns an error, the webhook will not be retried.