Webhooks

Receive real-time notifications when events occur on Menon Mobility.

Overview

Webhooks allow your application to receive HTTP callbacks when events happen, such as:

• New listing created or updated
• Message received
• Subscription changed
• Payment processed
• Booking events

Endpoints Overview

Method	Endpoint	Description	Auth
GET	/api/seller/webhooks	List your webhooks	Seller
POST	/api/seller/webhooks	Create webhook	Seller
PATCH	/api/seller/webhooks/:id	Update webhook	Seller
DELETE	/api/seller/webhooks/:id	Delete webhook	Seller
POST	/api/seller/webhooks/:id/test	Send test event	Seller

Setting Up Webhooks

Via Dashboard

1. Go to Dashboard > Settings > API > Webhooks
2. Click "Add Webhook"
3. Enter your endpoint URL
4. Select events to subscribe to
5. Save and copy the signing secret

Via API

POST /api/seller/webhooks
Authorization: Bearer YOUR_JWT_TOKEN
Content-Type: application/json

{
  "url": "https://yourapp.com/webhooks/menon",
  "events": [
    "listing.created",
    "listing.updated",
    "message.received"
  ]
}

Response

{
  "success": true,
  "data": {
    "webhook": {
      "id": "wh_abc123",
      "url": "https://yourapp.com/webhooks/menon",
      "events": ["listing.created", "listing.updated", "message.received"],
      "status": "active",
      "secret": "whsec_abc123...",
      "createdAt": "2024-01-15T10:00:00Z"
    }
  }
}

Secret Storage

Store the webhook secret securely. It is only shown once at creation time.

Webhook Events

Listing Events

Event	Description
listing.created	New listing created
listing.updated	Listing updated
listing.published	Listing published
listing.unpublished	Listing unpublished
listing.deleted	Listing deleted
listing.sold	Listing marked as sold

Message Events

Event	Description
message.received	New message received
message.read	Message marked as read
conversation.created	New conversation started

Inquiry Events

Event	Description
inquiry.created	New inquiry on listing
inquiry.responded	Inquiry responded to

Subscription Events

Event	Description
subscription.created	New subscription
subscription.updated	Plan changed
subscription.canceled	Subscription canceled
subscription.renewed	Auto-renewal processed

Payment Events

Event	Description
payment.succeeded	Payment successful
payment.failed	Payment failed
invoice.created	Invoice generated
invoice.paid	Invoice paid

User Events

Event	Description
user.created	New user registered
user.verified	User verified

Webhook Payload

Standard Format

All webhooks follow this format:

{
  "id": "evt_abc123",
  "type": "listing.created",
  "created_at": "2024-01-15T10:30:00Z",
  "data": {
    // Event-specific data
  }
}

Example: listing.created

{
  "id": "evt_abc123",
  "type": "listing.created",
  "created_at": "2024-01-15T10:30:00Z",
  "data": {
    "listing": {
      "id": "lst_xyz",
      "title": "2021 Volvo FH 500",
      "price": 85000,
      "currency": "EUR",
      "category": "trucks",
      "status": "draft",
      "seller_id": "sel_123",
      "created_at": "2024-01-15T10:30:00Z"
    }
  }
}

Example: message.received

{
  "id": "evt_def456",
  "type": "message.received",
  "created_at": "2024-01-15T14:30:00Z",
  "data": {
    "message": {
      "id": "msg_789",
      "conversation_id": "conv_123",
      "content": "Is this vehicle still available?",
      "sender": {
        "id": "usr_456",
        "name": "John Smith"
      },
      "listing": {
        "id": "lst_xyz",
        "title": "2021 Volvo FH 500"
      },
      "sent_at": "2024-01-15T14:30:00Z"
    }
  }
}

Example: subscription.created

{
  "id": "evt_ghi789",
  "type": "subscription.created",
  "created_at": "2024-01-15T15:00:00Z",
  "data": {
    "subscription": {
      "id": "sub_abc",
      "plan": {
        "id": "plan_professional",
        "name": "Professional"
      },
      "user_id": "usr_123",
      "status": "active",
      "billing_cycle": "monthly",
      "price": {
        "amount": 149,
        "currency": "USD"
      },
      "created_at": "2024-01-15T15:00:00Z"
    }
  }
}

Verifying Webhooks

Signature Verification

Each webhook includes a signature header:

X-Menon-Signature: sha256=abc123...

Verify in Node.js

const crypto = require('crypto');

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

  return `sha256=${expectedSignature}` === signature;
}

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

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

  // Process webhook
  const event = req.body;
  console.log('Received:', event.type);

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

Verify in Python

import hmac
import hashlib

def verify_webhook(payload, signature, secret):
    expected = hmac.new(
        secret.encode(),
        payload.encode(),
        hashlib.sha256
    ).hexdigest()
    return f'sha256={expected}' == signature

Handling Webhooks

Best Practices

Return 200 Quickly

Respond with 200 status immediately, then process asynchronously.

Handle Duplicates

Events may be sent multiple times. Use event ID for idempotency.

Verify Signatures

Always verify webhook signatures in production.

Retry Policy

Failed webhooks are retried:

Attempt	Delay
1	Immediate
2	1 minute
3	5 minutes
4	30 minutes
5	2 hours
6	24 hours

After 6 failures, webhook is disabled.

Managing Webhooks

List Webhooks

GET /v1/webhooks
Authorization: Bearer YOUR_API_KEY

Get Webhook

GET /v1/webhooks/wh_abc123
Authorization: Bearer YOUR_API_KEY

Update Webhook

PUT /v1/webhooks/wh_abc123
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "events": ["listing.created", "listing.updated"],
  "status": "active"
}

Delete Webhook

DELETE /v1/webhooks/wh_abc123
Authorization: Bearer YOUR_API_KEY

Webhook Logs

View Delivery Logs

GET /v1/webhooks/wh_abc123/logs
Authorization: Bearer YOUR_API_KEY

Response

{
  "success": true,
  "data": {
    "logs": [
      {
        "id": "log_123",
        "event_id": "evt_abc",
        "event_type": "listing.created",
        "status": "delivered",
        "response_code": 200,
        "response_time_ms": 150,
        "delivered_at": "2024-01-15T10:30:01Z"
      },
      {
        "id": "log_124",
        "event_id": "evt_def",
        "event_type": "message.received",
        "status": "failed",
        "response_code": 500,
        "error": "Internal Server Error",
        "retry_count": 2,
        "next_retry": "2024-01-15T10:35:00Z"
      }
    ]
  }
}

Retry Failed Webhook

POST /v1/webhooks/wh_abc123/logs/log_124/retry
Authorization: Bearer YOUR_API_KEY

Testing Webhooks

Send Test Event

POST /v1/webhooks/wh_abc123/test
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "event_type": "listing.created"
}

Using Webhook Tester

1. Go to Settings > API > Webhooks
2. Click on webhook
3. Click "Send Test"
4. Select event type
5. View delivery result

Related Topics

• Authentication
• API Overview