Skip to main content

​
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"
  }'

​
Parameters

ParameterTypeRequiredDescription
urlstringYesHTTPS endpoint URL
eventsarrayYesEvents to subscribe to
secretstringYesShared secret for verification

​
List Webhooks

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

​
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"
  }'

​
Delete Webhook

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

​
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

EventDescription
loan.createdLoan request created
loan.fundedLoan has been funded
loan.repaidLoan fully repaid
loan.partial_paymentPartial payment received
loan.overdueLoan is overdue
loan.defaultedLoan marked as default

​
Vault Events

EventDescription
vault.depositUSDC deposited
vault.withdrawUSDC withdrawn
vault.yield_distributedYield distribution occurred

​
Social Vault Events

EventDescription
social_vault.withdrawal_requestedLarge withdrawal requested
social_vault.withdrawal_approvedWithdrawal approved
social_vault.withdrawal_executedWithdrawal completed
social_vault.lockedVault locked (duress)

​
User Events

EventDescription
user.trust_score_updatedTrust Score changed
user.level_upUser leveled up
user.guardian_addedGuardian relationship created

​
Retry Policy

Failed webhook deliveries are retried:
AttemptDelay
1Immediate
21 minute
35 minutes
430 minutes
52 hours
624 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"

​
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"
  }'

​
Best Practices

Return 200 OK within 5 seconds. Process asynchronously if needed.
Use the id field to deduplicate. We may retry successful deliveries.
Always verify the x-usmewe-signature header.
Webhook URLs must use HTTPS with valid certificates.

​
Error Responses

CodeErrorDescription
400INVALID_URLURL is not valid HTTPS
400INVALID_EVENTSUnknown event types
404WEBHOOK_NOT_FOUNDWebhook doesn’t exist
409URL_EXISTSURL already registered