Asaas Webhooks

Asaas Webhooks

When to Use This Skill

• How do I receive Asaas webhooks?
• How do I verify an Asaas webhook? Why is my asaas-access-token check failing?
• How do I handle PAYMENT_RECEIVED, PAYMENT_CONFIRMED, or PAYMENT_OVERDUE events?
• How do I stop processing duplicate Asaas webhook events?
• Why did Asaas pause my webhook queue?

Verification (core)

Asaas webhooks are not signed. There is no HMAC and no timestamp. When you create the webhook you choose an authToken (32-255 characters, no whitespace, and not your Asaas API key). Asaas sends it unchanged in the asaas-access-token header on every delivery, so verification is a constant-time comparison against the token you stored.

javascriptCopy code
const crypto = require('crypto');

function verifyAsaasToken(receivedToken, expectedToken) {
  if (!receivedToken || !expectedToken) return false;
  // Hash both sides so timingSafeEqual always gets equal-length buffers.
  const a = crypto.createHash('sha256').update(receivedToken).digest();
  const b = crypto.createHash('sha256').update(expectedToken).digest();
  return crypto.timingSafeEqual(a, b);
}

// header: req.headers['asaas-access-token'], secret: process.env.ASAAS_WEBHOOK_TOKEN

Check the token before parsing or acting on the body, then dedupe on the event id (delivery is at-least-once) and answer 200 quickly. Asaas pauses the queue after 15 consecutive failures.

For complete handlers with tests, see examples/express/, examples/nextjs/, examples/fastapi/.

Common Event Types

The payload is { id, event, dateCreated, account, payment } (the resource key is subscription, transfer, or invoice for those families).

See references/overview.md for the full list.

Environment Variables

bashCopy code
ASAAS_WEBHOOK_TOKEN=your_32_to_255_char_auth_token   # the authToken set on the webhook

Local Development

bashCopy code
npx hookdeck-cli listen 3000 asaas --path /webhooks/asaas

No account required: the CLI creates a guest account on first run and provides a local tunnel plus a web UI for inspecting requests. Use port 8000 for the FastAPI example.

Reference Materials

• references/overview.md - What Asaas webhooks are, payload shape, event list
• references/setup.md - Create the webhook and authToken, send type, IP allowlist
• references/verification.md - Token check details and gotchas

Recommended: webhook-handler-patterns

Install webhook-handler-patterns alongside this skill for cross-cutting concerns:

• Handler sequence
• Idempotency
• Error handling
• Retry logic

Related Skills

• paystack-webhooks - Payments webhooks for African markets
• razorpay-webhooks - Payments webhooks for India
• mollie-webhooks - European payments webhooks
• paypal-webhooks - PayPal payment events
• airwallex-webhooks - Cross-border payments
• checkout-com-webhooks - Payment gateway events
• stripe-webhooks - Stripe payment events with HMAC signatures
• webhook-handler-patterns - Idempotency, error handling, retry logic
• hookdeck-event-gateway - Production webhook infrastructure