Diddo uses webhooks to notify your application when important events occur in real time — such as checkout initialization, payment updates, or fulfillment changes.

Webhooks are delivered as HTTPS POST requests to your configured endpoint and allow your system to stay in sync without polling.

This section covers:

• Webhook overview
• Setting up a webhook endpoint
• Event payload structure
• Verifying webhook signatures
• Idempotency & retries
• Security best practices

📘 Note: Full request/response schemas for webhook management are available in the API reference

🔁 Webhook Overview

• Webhooks are sent as HTTPS POST requests
• Each request represents one event
• Events are signed to ensure authenticity
• Deliveries may be retried if your endpoint does not acknowledge receipt

Typical use cases:

• Track checkout lifecycle events
• Trigger internal workflows (orders, fulfillment, analytics)
• Keep downstream systems in sync with Diddo

💡Event Types

🧩 Set Up a Webhook Endpoint

Create an endpoint in your application that accepts POST requests with a JSON body.

Once your endpoint is live, register it in Diddo using the Create Webhook Subscription endpoint and store the returned webhook signing secret securely.

⚠️ The webhook secret is shown only once. Store it safely.

Operational requirements:

• Endpoint must be publicly accessible
• Must respond within 20 seconds
• Must return a 2xx status code to acknowledge receipt

📨 Webhook Requests

HTTP Method = POST

Headers

📦 Event Object

Each webhook delivers a single event with the following structure:

json

Examples

Event Type: checkout.initialized

sql

Event Type: checkout.in_progress

sql

Event Type: checkout.succeeded

json

Event Type: checkout.failed

sql

🔐 Verifying Webhook Signatures

Always verify webhook signatures before processing events.

Diddo signs each webhook payload using HMAC-SHA256 with your webhook secret.

Verification Flow

1. Read the raw request body
2. Compute an HMAC-SHA256 hash using your webhook secret
3. Compare it to the value in X-Diddo-Webhook-Signature
4. Reject the request if the signatures don’t match

🧪 Signature Verification Examples

Python

python

Node.js

javascript

Important: Use the raw request body. Do not stringify parsed JSON.

Go

go

✅ Responding to Webhooks

• Return a 2xx status code to acknowledge receipt
• Do not perform long-running work in the request handler
• Queue the event and process it asynchronously

⏱️ Requests must be processed within 20 seconds

♻️ Idempotency

Webhook events may be delivered more than once.

Use the X-Webhook-Id header as an idempotency key to deduplicate events in your system.

Recommended approach:

• Store processed webhook IDs
• Ignore events you’ve already handled

🔄 Retries

If your endpoint fails or returns a non-2xx response, Diddo retries delivery using exponential backoff:

After all retries are exhausted, the delivery is marked as failed_permanent.

🔒 Security Best Practices

• Always use HTTPS
• Verify webhook signatures
• Store webhook secrets securely
• Reject invalid or unsigned requests
• Avoid logging raw secrets or payloads

🔧 Managing Webhook Subscriptions

Diddo provides APIs to manage webhook subscriptions:

• Create new webhook subscriptions
• List all webhook subscriptions
• Get a specific webhook subscription
• Update webhook subscription
• Delete webhook subscription

See the Webhook API reference for details.