Skip to main content

​
Overview

Webhooks allow you to receive real-time notifications about events in your Metrifox account. When specific events occur (such as a customer being created, a subscription being cancelled, or an invoice being generated), Metrifox will send an HTTPS POST request to your configured webhook URL with the event details. This enables you to:
  • Automate workflows based on Metrifox events
  • Keep your systems in sync with Metrifox data
  • Trigger actions in your application when important events occur
  • Monitor and log all webhook deliveries

​
How Webhooks Work

  1. Configure a webhook in your Metrifox dashboard by providing a URL endpoint and selecting which events you want to receive
  2. Metrifox sends HTTPS POST requests to your URL whenever the selected events occur
  3. Your server processes the webhook and performs any necessary actions
  4. Delivery logs track all webhook attempts, allowing you to monitor success and failures

​
Setting Up Webhooks

Webhook configuration is managed entirely through the Metrifox dashboard UI.

​
Accessing Webhook Settings

Navigate to your Metrifox dashboard and access the webhook configuration page. This is typically found in the Developers section. Create Webhook

​
Creating a Webhook Configuration

To create a new webhook:
  1. Click Create Webhook
  2. Enter a name for your webhook (e.g., “Production Webhook” or “Customer Events”)
  3. Enter your webhook URL - must be a valid HTTPS endpoint
  4. Select the event types you want to receive notifications for
  5. Click Create
Important: Your webhook URL must use HTTPS. HTTP URLs are not supported for security reasons.
Create Webhook

​
Selecting Event Types

You can select one or more event types when creating a webhook. The available event types are organized by category:
  • Customer Events: customer.created, customer.updated, customer.deleted
  • Order Events: order.created
  • Subscription Events: subscription.created, subscription.cancelled, subscription.cancel_scheduled
  • Invoice Events: invoice.created
  • Credit Events: credit.purchased
You can subscribe to multiple event types in a single webhook configuration, or create separate webhooks for different event categories.
Multiple Webhooks for Same Event: If you create multiple webhooks and subscribe to the same event type in those webhooks, Metrifox will only send the webhook to the most recently created webhook configuration for that event. This ensures each event is delivered to a single endpoint to avoid duplicate processing.

​
Webhook Secret

When you create a webhook, Metrifox automatically generates a unique webhook secret (starting with whsec_). This secret is used to verify that webhook requests are actually coming from Metrifox. You can always find your webhook secret on your dashboard. Webhook Secret

​
Testing Webhooks

Before relying on webhooks in production, you should test your webhook endpoint to ensure it’s working correctly.

​
Testing Your Webhook

  1. Navigate to your webhook configuration in the dashboard
  2. Click the Test button
  3. Metrifox will send a test webhook to your URL with a sample payload
  4. Check your server logs to verify the webhook was received
  5. Review the delivery log to see the test attempt status
Test webhooks have event type “webhook.test”, and have the X-Webhook-Test: true header, so you can distinguish them from real events. Webhook Test

​
Viewing Delivery Logs

All webhook delivery attempts are logged and can be viewed in the dashboard.

​
Accessing Delivery Logs

  1. Navigate to your webhook configuration
  2. Click on the delivery log whose history you intend to view
  3. You’ll see a list of all webhook delivery attempts with:
    • Event type
    • Delivery status (success, failed, pending)
    • Number of attempts
    • Timestamp of last attempt
Delivery Logs

​
Delivery Log Details

Clicking on a specific delivery log shows:
  • Full webhook payload that was sent
  • Response status code and body from your server
  • All delivery attempts with timestamps
  • Error messages if delivery failed
Delivery Log Details

​
Resending Failed Webhooks

If a webhook delivery fails, you can manually resend it:
  1. Open the delivery log for the failed webhook
  2. Click Resend
  3. Metrifox will attempt to deliver the webhook again
Manually Resend Webhooks
Failed webhooks are automatically retried by Metrifox with exponential backoff. Manual resend is useful if you want to retry immediately or after fixing an issue with your endpoint.

​
Webhook Payload Structure

All webhooks follow a consistent structure: 
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "type": "customer.created",
  "created_at": 1704067200000,
  "data": {
    // Event-specific data
  }
}

​
Payload Fields

  • id: Unique identifier for this event (UUID)
  • type: The event type (e.g., customer.created, subscription.cancelled)
  • created_at: Unix timestamp in milliseconds when the event occurred
  • data: Event-specific data object containing the details of what happened

​
Webhook Headers

Metrifox includes the following headers with each webhook request:
  • Content-Type: application/json - The request body is JSON
  • X-Webhook-Signature: <signature> - HMAC SHA256 signature for verification
  • X-Webhook-Test: true - Present only for test webhooks
  • User-Agent: Metrifox-Webhooks/1.0 - Identifies the request as coming from Metrifox

​
Signature Verification

To ensure webhooks are actually coming from Metrifox, you should verify the signature on each request.

​
How to Verify

  1. Get the X-Webhook-Signature header value
  2. Compute HMAC SHA256 of the request body using your webhook secret
  3. Compare the computed signature with the header value

​
Example Verification Code

JavaScript/Node.js: 
const crypto = require('crypto');

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

// Usage
const signature = req.headers['x-webhook-signature'];
const isValid = verifyWebhookSignature(
  JSON.stringify(req.body),
  signature,
  webhookSecret
);
Python: 
import hmac
import hashlib

def verify_webhook_signature(payload, signature, secret):
    computed = hmac.new(
        secret.encode('utf-8'),
        payload.encode('utf-8'),
        hashlib.sha256
    ).hexdigest()
    
    return hmac.compare_digest(computed, signature)

# Usage
signature = request.headers.get('X-Webhook-Signature')
is_valid = verify_webhook_signature(
    json.dumps(request.json),
    signature,
    webhook_secret
)
Ruby: 
require 'openssl'

def verify_webhook_signature(payload, signature, secret)
  computed = OpenSSL::HMAC.hexdigest('SHA256', secret, payload)
  computed == signature
end

# Usage
signature = request.headers['X-Webhook-Signature']
is_valid = verify_webhook_signature(
  request.body.read,
  signature,
  webhook_secret
)
Security: Always verify webhook signatures in production. Without verification, your endpoint could accept requests from unauthorized sources.

​
Delivery and Retry Logic

Metrifox automatically retries failed webhook deliveries with exponential backoff.

​
Retry Schedule

  • Attempt 1: Immediate
  • Attempt 2: ~15 seconds later
  • Attempt 3: ~30 seconds later
  • Attempt 4: ~1 minute later
  • Attempt 5: ~5 minutes later
  • Attempt 6: ~10 minutes later
  • Attempt 7: ~20 minutes later
  • Attempt 8: ~40 minutes later
  • Attempt 9: ~70 minutes later
  • Attempt 10: ~2 hours later (final attempt)
After 10 automatic retry attempts, the webhook is marked as failed. You can manually resend it from the delivery logs if needed.

​
Success Criteria

A webhook delivery is considered successful if your server returns any HTTP status code in the 2XX range (200-299). Any other status code (including 1XX, 3XX, 4XX, 5XX) or network/timeout errors will be considered a failure and will trigger a retry.

​
Timeouts

Metrifox webhook requests have a 10-second timeout. If your server doesn’t respond within this time, the request will be retried.

​
Best Practices

​
1. Use HTTPS Endpoints

Always use HTTPS for your webhook endpoints. HTTP is not supported and will be rejected.

​
2. Verify Signatures

Always verify webhook signatures to ensure requests are authentic. This prevents unauthorized access to your systems.

​
3. Respond Quickly and Process Asynchronously

Your webhook handler should respond with a 200 status code immediately without processing the webhook synchronously. This is a best practice that prevents timeouts and ensures reliable delivery. Recommended approach:
  1. Verify the webhook signature
  2. Validate the payload structure
  3. Return 200 OK immediately
  4. Enqueue a background job to process the webhook asynchronously
This pattern ensures your endpoint responds quickly (within milliseconds), reducing the risk of timeouts and allowing Metrifox to mark the delivery as successful. The actual processing (updating databases, sending emails, triggering workflows, etc.) happens in the background job. Example pattern: 
// Good: Respond immediately, process later
app.post('/webhooks', (req, res) => {
  // Verify signature
  if (!verifySignature(req)) {
    return res.status(401).send('Invalid signature');
  }
  
  // Return 200 immediately
  res.status(200).send('OK');
  
  // Process asynchronously
  processWebhookJob.enqueue(req.body);
});
Avoid processing webhooks synchronously, as this can lead to timeouts and failed deliveries.

​
4. Handle Duplicates

Webhooks may be delivered multiple times due to retries. Make your webhook handlers idempotent by checking if you’ve already processed an event (using the event id).

​
5. Log Everything

Log all incoming webhooks, including the payload and response. This helps with debugging and auditing.

​
6. Test in Development

Use the test webhook feature to verify your endpoint works before relying on it in production.

​
7. Monitor Delivery Logs

Regularly check delivery logs to ensure webhooks are being delivered successfully. Set up alerts for repeated failures.

​
8. Keep Secrets Secure

Store webhook secrets securely (e.g., environment variables, secret management services). Never commit them to version control.

​
Supported Event Types

For detailed information about each webhook event type, including payload examples, see the Webhook Events Reference. Available event types: