Skip to main content
Receive real-time notifications for payment events.

​
Overview

Webhooks allow your server to receive automatic notifications when events occur in your Atlas account. This is essential for:
  • Order fulfillment after successful payments
  • Sending confirmation emails
  • Updating inventory
  • Handling failed payments

​
Setting Up Webhooks

  1. Go to your Dashboard
  2. Add your endpoint URL (e.g., https://yoursite.com/webhooks/atlas)
  3. Select the events you want to receive
  4. Copy your webhook signing secret

​
Event Types

EventDescription
payment.authorizedPayment was authorized (manual capture)
payment.capturedPayment was captured successfully
payment.failedPayment was declined or failed
payment.refundedPayment was refunded (full or partial)
session.expiredPayment session expired
session.canceledPayment session was canceled

​
Webhook Payload

{
  "id": "evt_1234567890",
  "type": "payment.captured",
  "created": "2024-01-15T10:30:00Z",
  "livemode": false,
  "data": {
    "object": {
      "id": "pay_8xM2nQ4vR7kL9pYz",
      "session_id": "sess_2xK9mN7vQ3pL8wYz",
      "amount": 4990,
      "currency": "USD",
      "status": "captured",
      "payment_method_type": "card",
      "card": {
        "brand": "visa",
        "last4": "4242"
      }
    }
  }
}

​
Verifying Signatures

Always verify webhook signatures to ensure requests are from Atlas: 
const crypto = require('crypto');

function verifyWebhookSignature(payload, signature, secret) {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  );
}

// In your webhook handler
app.post('/webhooks/atlas', (req, res) => {
  const signature = req.headers['x-atlas-signature'];
  const payload = JSON.stringify(req.body);

  if (!verifyWebhookSignature(payload, signature, process.env.WEBHOOK_SECRET)) {
    return res.status(401).send('Invalid signature');
  }

  const event = req.body;

  switch (event.type) {
    case 'payment.captured':
      // Fulfill the order
      await fulfillOrder(event.data.object.session_id);
      break;
    case 'payment.failed':
      // Notify the customer
      await notifyPaymentFailed(event.data.object);
      break;
  }

  res.status(200).send('OK');
});

​
Best Practices

  1. Return 200 quickly - Process webhooks asynchronously to avoid timeouts
  2. Handle duplicates - Use idempotency keys or check if you’ve already processed the event
  3. Verify signatures - Always verify the x-atlas-signature header
  4. Use HTTPS - Webhook endpoints must use HTTPS in production
  5. Retry logic - Atlas retries failed webhooks with exponential backoff

​
Retry Policy

If your endpoint returns a non-2xx status code, Atlas will retry:
AttemptDelay
1Immediate
25 minutes
330 minutes
42 hours
524 hours
After 5 failed attempts, the webhook is marked as failed and won’t be retried.