Webhooks

Webhooks allow you to build or set up integrations that subscribe to certain events on Melon. When one of those events is triggered, we'll send a HTTP POST payload to the webhook's configured URL.

This is the recommended way to track verification statuses, rather than polling the API.

Configuring Webhooks

You can configure webhook endpoints directly from the Developers section of your Dashboard. Each endpoint can subscribe to one or more events, and will be assigned a unique Secret for verifying webhook signatures.

Event Types

Currently, Melon supports the following outbound webhook events:

customer.created
- Triggered when a new customer is successfully added to the system for verification.
customer.updated
- Triggered when a customer's basic details (phone, email, etc.) are updated.
verification.assigned
- Triggered when a physical address verification job is assigned to a Melon field agent.
verification.in_review
- Triggered when an agent has submitted their field report, and it is pending internal review.
verification.completed
- Triggered when the customer's overall verification process has been successfully finalized and approved.
verification.rejected
- Triggered when the verification process fails (e.g., fraudulent document, incorrect address) and is rejected.

Webhook Payload Structure

All webhook payloads share a common structure:

{
  "eventId": "evt_1234567890",
  "event": "verification.completed",
  "timestamp": "2024-06-10T14:30:00Z",
  "data": {
    "_id": "60d5ecb8b392...",
    "firstName": "Babatunde",
    "lastName": "Ogunlesi",
    "status": "VERIFIED",
    // ... Full customer object
  }
}

Security & Signatures

To ensure that the webhook was actually sent by Melon and not a malicious third party, every webhook request includes an x-melon-signature header.

The signature is an HMAC SHA-256 hash of the JSON request body, signed using your endpoint's Webhook Secret.

Verifying the Signature

Here is an example of how to verify the webhook signature in Node.js:

const crypto = require('crypto');

function verifySignature(payloadBody, signatureHeader, webhookSecret) {
  const computedSignature = crypto
    .createHmac('sha256', webhookSecret)
    .update(payloadBody)
    .digest('hex');
    
  return computedSignature === signatureHeader;
}

If the signature you compute matches the x-melon-signature header, the webhook is legitimate.

Retries and Failures

If your server responds with a status code outside the 2xx range (e.g., 404, 500), Melon will assume the webhook delivery failed.

We utilize an exponential backoff strategy for retrying failed webhooks over a period of up to 3 days. Ensure your webhook handler acknowledges receipt quickly (by returning a 200 OK) before performing any long-running processing tasks.

Webhook Events