Webhooks

Receive real-time notifications when events occur in usmewe.

Overview

Webhooks allow your application to receive HTTP POST requests when specific events happen, enabling real-time integrations.

┌─────────────────────────────────────────────────────────────────┐
│  usmewe                          Your Server                    │
│     │                                 │                         │
│     │  Event occurs                   │                         │
│     │  (loan.funded)                  │                         │
│     │                                 │                         │
│     │  ───────POST /webhook───────►   │                         │
│     │                                 │  Process event          │
│     │  ◄─────── 200 OK ───────────    │                         │
│     │                                 │                         │
└─────────────────────────────────────────────────────────────────┘

Register Webhook

Create a new webhook endpoint.

curl -X POST "https://api.usmewe.com/v1/webhooks" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://yourapp.com/webhooks/usmewe",
    "events": ["loan.funded", "loan.repaid", "loan.overdue"],
    "secret": "your_webhook_secret"
  }'

{
  "success": true,
  "data": {
    "id": "wh_abc123",
    "url": "https://yourapp.com/webhooks/usmewe",
    "events": ["loan.funded", "loan.repaid", "loan.overdue"],
    "status": "active",
    "createdAt": "2024-01-15T12:00:00Z"
  }
}

Parameters

Parameter	Type	Required	Description
`url`	string	Yes	HTTPS endpoint URL
`events`	array	Yes	Events to subscribe to
`secret`	string	Yes	Shared secret for verification

List Webhooks

Get all registered webhooks.

curl -X GET "https://api.usmewe.com/v1/webhooks" \
  -H "Authorization: Bearer YOUR_TOKEN"

{
  "success": true,
  "data": [
    {
      "id": "wh_abc123",
      "url": "https://yourapp.com/webhooks/usmewe",
      "events": ["loan.funded", "loan.repaid"],
      "status": "active",
      "lastDelivery": {
        "timestamp": "2024-01-15T10:00:00Z",
        "status": "success"
      }
    }
  ]
}

Update Webhook

Update webhook configuration.

curl -X PATCH "https://api.usmewe.com/v1/webhooks/{webhookId}" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "events": ["loan.funded", "loan.repaid", "vault.deposit"],
    "status": "active"
  }'

{
  "success": true,
  "data": {
    "id": "wh_abc123",
    "url": "https://yourapp.com/webhooks/usmewe",
    "events": ["loan.funded", "loan.repaid", "vault.deposit"],
    "status": "active"
  }
}

Delete Webhook

Remove a webhook.

curl -X DELETE "https://api.usmewe.com/v1/webhooks/{webhookId}" \
  -H "Authorization: Bearer YOUR_TOKEN"

{
  "success": true,
  "message": "Webhook deleted"
}

Webhook Payload

All webhooks receive payloads in this format:

{
  "id": "evt_xyz789",
  "event": "loan.funded",
  "timestamp": "2024-01-15T12:00:00Z",
  "data": {
    "loanId": "loan_abc123",
    "userId": "user_def456",
    "amount": "50.00"
  }
}

Verifying Webhooks

Verify webhook authenticity using the signature header:

import crypto from 'crypto';

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

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(`sha256=${expectedSignature}`)
  );
}

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

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

  // Process webhook
  const { event, data } = req.body;
  // ...

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

Available Events

Loan Events

Event	Description
`loan.created`	Loan request created
`loan.funded`	Loan has been funded
`loan.repaid`	Loan fully repaid
`loan.partial_payment`	Partial payment received
`loan.overdue`	Loan is overdue
`loan.defaulted`	Loan marked as default

Vault Events

Event	Description
`vault.deposit`	USDC deposited
`vault.withdraw`	USDC withdrawn
`vault.yield_distributed`	Yield distribution occurred

Event	Description
`social_vault.withdrawal_requested`	Large withdrawal requested
`social_vault.withdrawal_approved`	Withdrawal approved
`social_vault.withdrawal_executed`	Withdrawal completed
`social_vault.locked`	Vault locked (duress)

User Events

Event	Description
`user.trust_score_updated`	Trust Score changed
`user.level_up`	User leveled up
`user.guardian_added`	Guardian relationship created

Retry Policy

Failed webhook deliveries are retried:

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

After 6 failed attempts, the webhook is marked as failing.

Get Delivery History

View webhook delivery attempts.

curl -X GET "https://api.usmewe.com/v1/webhooks/{webhookId}/deliveries?limit=10" \
  -H "Authorization: Bearer YOUR_TOKEN"

{
  "success": true,
  "data": [
    {
      "id": "del_1",
      "event": "loan.funded",
      "status": "success",
      "statusCode": 200,
      "timestamp": "2024-01-15T10:00:00Z",
      "duration": 150
    },
    {
      "id": "del_2",
      "event": "loan.repaid",
      "status": "failed",
      "statusCode": 500,
      "timestamp": "2024-01-15T09:00:00Z",
      "duration": 5000,
      "error": "Timeout"
    }
  ]
}

Test Webhook

Send a test event to your webhook.

curl -X POST "https://api.usmewe.com/v1/webhooks/{webhookId}/test" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "event": "loan.funded"
  }'

{
  "success": true,
  "data": {
    "delivered": true,
    "statusCode": 200,
    "duration": 120
  }
}

Best Practices

Respond quickly

Return 200 OK within 5 seconds. Process asynchronously if needed.

Handle duplicates

Use the id field to deduplicate. We may retry successful deliveries.

Verify signatures

Always verify the x-usmewe-signature header.

Use HTTPS

Webhook URLs must use HTTPS with valid certificates.

Error Responses

Code	Error	Description
400	`INVALID_URL`	URL is not valid HTTPS
400	`INVALID_EVENTS`	Unknown event types
404	`WEBHOOK_NOT_FOUND`	Webhook doesn’t exist
409	`URL_EXISTS`	URL already registered

API Overview

API Endpoints

Webhooks

Webhooks

Overview

Register Webhook

Parameters

List Webhooks

Update Webhook

Delete Webhook

Webhook Payload

Verifying Webhooks

Available Events

Loan Events

Vault Events

User Events

Retry Policy

Get Delivery History

Test Webhook

Best Practices

Error Responses

​Webhooks

​Overview

​Register Webhook

​Parameters

​List Webhooks

​Update Webhook

​Delete Webhook

​Webhook Payload

​Verifying Webhooks

​Available Events

​Loan Events

​Vault Events

​Social Vault Events

​User Events

​Retry Policy

​Get Delivery History

​Test Webhook

​Best Practices

​Error Responses

Webhooks

Overview

Register Webhook

Parameters

List Webhooks

Update Webhook

Delete Webhook

Webhook Payload

Verifying Webhooks

Available Events

Loan Events

Vault Events

Social Vault Events

User Events

Retry Policy

Get Delivery History

Test Webhook

Best Practices

Error Responses