​
Webhooks Configuration

Webhooks allow you to receive real-time notifications when events occur in your Devdraft account. Get instant updates about payments, refunds, disputes, and other important activities without polling the API.

​
What are Webhooks?

Webhooks are HTTP callbacks that send event data to your server when specific actions occur:
  • Real-time Notifications: Get instant updates about payment events
  • Automated Workflows: Trigger actions in your application based on events
  • Data Synchronization: Keep your systems in sync with Devdraft
  • Reduced API Calls: No need to constantly poll for updates
Webhooks are essential for building responsive applications that react to payment events in real-time.

​
Use Cases

Common webhook use cases include:

Payment Processing

  • Notify customers of successful payments
  • Update inventory when orders are placed
  • Trigger order fulfillment workflows
  • Send confirmation emails

Subscription Management

  • Handle subscription renewals
  • Process failed payments
  • Update user access levels
  • Send payment reminders

Dispute Handling

  • Alert teams to new disputes
  • Automate evidence collection
  • Update order status
  • Notify customer service

Analytics & Reporting

  • Update dashboards in real-time
  • Track conversion rates
  • Monitor payment performance
  • Generate automated reports

​
Creating a Webhook

1

Navigate to Webhooks

In the Devdraft Console, go to Settings → Webhooks.
You’ll see your existing webhooks or an empty state if you’re just getting started.
2

Create New Webhook

Click Add Webhook to create a new webhook endpoint.
3

Configure Endpoint

Enter your webhook URL and select the events you want to receive:
  • Endpoint URL: Your server endpoint that will receive webhook data
  • Events: Select which events to listen for
  • Description: Optional description for your reference
4

Set Up Security

Configure webhook security settings:
  • Signing Secret: Generate a secret to verify webhook authenticity
  • Retry Settings: Configure retry behavior for failed deliveries
  • IP Restrictions: Limit webhook sources to specific IP addresses
5

Test Webhook

Send a test webhook to verify your endpoint is working correctly.
Webhook configuration form with URL, events, and security settings

Webhook configuration page showing endpoint setup and event selection

​
Supported Events

Devdraft sends webhooks for various events. Here are the most commonly used ones:

​
Payment Events

​
payment_events
object
Events related to payment processing and status changes.

​
Refund Events

​
refund_events
object
Events related to refund processing.

​
Dispute Events

​
dispute_events
object
Events related to payment disputes and chargebacks.

​
Subscription Events

​
subscription_events
object
Events related to subscription management.

​
Webhook Security

Protect your webhook endpoints with proper security measures:

​
Signing Secret

Always verify webhook signatures to ensure requests come from Devdraft and haven’t been tampered with.
1

Generate Signing Secret

Create a unique signing secret in the webhook configuration.
Use a strong, random string that’s at least 32 characters long.
2

Verify Signature

Implement signature verification in your webhook handler:
const crypto = require('crypto');

function verifyWebhookSignature(payload, signature, secret) {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(payload, 'utf8')
    .digest('hex');
  
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  );
}
3

Test Verification

Verify that your signature checking works with test webhooks.

​
IP Restrictions

Security Best Practices

  • Whitelist Devdraft’s IP addresses
  • Use HTTPS endpoints only
  • Implement rate limiting
  • Log all webhook requests
  • Monitor for suspicious activity

​
Webhook Payload Structure

All webhook payloads follow a consistent structure: 
{
  "id": "evt_1234567890abcdef",
  "object": "event",
  "api_version": "2024-01-01",
  "created": 1640995200,
  "data": {
    "object": {
      // Event-specific data
    }
  },
  "livemode": false,
  "pending_webhooks": 1,
  "request": {
    "id": "req_1234567890abcdef",
    "idempotency_key": "ik_1234567890abcdef"
  },
  "type": "payment.succeeded"
}

​
Common Payload Fields

​
id
string
required
Unique identifier for the webhook event.
​
type
string
required
The type of event that occurred (e.g., “payment.succeeded”).
​
created
integer
required
Unix timestamp when the event was created.
​
data
object
required
Contains the object that triggered the event with all relevant data.
​
livemode
boolean
required
Whether this event occurred in live mode (true) or test mode (false).

​
Handling Webhooks

Implement proper webhook handling in your application:

​
Webhook Endpoint Requirements

Endpoint Requirements

  • Must respond with HTTP 200 status code
  • Should respond within 10 seconds
  • Must handle duplicate events gracefully
  • Should implement idempotency
  • Must verify webhook signatures

​
Example Webhook Handler

const express = require('express');
const crypto = require('crypto');

const app = express();
app.use(express.raw({ type: 'application/json' }));

app.post('/webhooks/devdraft', (req, res) => {
  const signature = req.headers['devdraft-signature'];
  const payload = req.body;
  
  // Verify webhook signature
  if (!verifySignature(payload, signature, process.env.WEBHOOK_SECRET)) {
    return res.status(400).send('Invalid signature');
  }
  
  const event = JSON.parse(payload);
  
  // Handle different event types
  switch (event.type) {
    case 'payment.succeeded':
      handlePaymentSucceeded(event.data.object);
      break;
    case 'payment.failed':
      handlePaymentFailed(event.data.object);
      break;
    case 'refund.created':
      handleRefundCreated(event.data.object);
      break;
    default:
      console.log(`Unhandled event type: ${event.type}`);
  }
  
  res.status(200).send('OK');
});

function handlePaymentSucceeded(payment) {
  // Update order status
  // Send confirmation email
  // Update inventory
  console.log(`Payment succeeded: ${payment.id}`);
}

​
Testing Webhooks

Test your webhook implementation thoroughly:

​
Test Events

1

Use Test Mode

Create webhooks in test mode to avoid affecting live data.
2

Send Test Webhooks

Use the Send Test Webhook button in the console to trigger test events.
3

Monitor Logs

Check your application logs to ensure webhooks are being received and processed.
4

Verify Processing

Confirm that your application correctly handles each event type.

​
Webhook Testing Tools

Testing Resources

  • Webhook.site: Temporary webhook endpoints for testing
  • ngrok: Expose local servers for webhook testing
  • Devdraft CLI: Send test webhooks from command line
  • Postman: Test webhook endpoints manually

​
Monitoring and Troubleshooting

Keep track of webhook performance and resolve issues quickly:

​
Webhook Dashboard

Webhook dashboard with delivery statistics and error logs

Webhook monitoring dashboard showing delivery status and error rates

​
Common Issues

​
Retry Configuration

Devdraft automatically retries failed webhook deliveries with exponential backoff.
  • Initial Retry: 1 minute after failure
  • Maximum Retries: 5 attempts
  • Retry Interval: Exponential backoff (1m, 2m, 4m, 8m, 16m)
  • Final Failure: After 5 failed attempts, webhook is marked as failed

​
Best Practices

Webhook Best Practices

  • Always verify webhook signatures
  • Implement idempotency to handle duplicates
  • Respond quickly (under 10 seconds)
  • Log all webhook events for debugging
  • Use HTTPS endpoints only
  • Monitor webhook delivery rates
  • Have fallback mechanisms for critical events
  • Test webhooks thoroughly before going live

​
Next Steps

Explore these related topics to enhance your webhook implementation:

API Events

Learn about all available webhook events and their payloads.

Settings

Configure webhook retry settings and security options.