Webhook Integration

OpenSylo supports both inbound webhooks (marketplace to OpenSylo) and outbound webhooks (OpenSylo to marketplace).

Inbound Webhooks (Marketplace to OpenSylo)

Your marketplace sends webhooks to OpenSylo to report repayment deductions and settlement events.

Endpoints

Endpoint	Purpose
`POST /api/v1/webhooks/marketplace/repayment`	Repayment events (deducted, failed, reversed)
`POST /api/v1/webhooks/marketplace/settlement`	Settlement events (created, transferred)

Required Headers

Header	Required	Description
`X-Marketplace-Signature`	Yes	HMAC-SHA256 signature of the payload
`X-Marketplace-Timestamp`	Yes	Unix timestamp (seconds) of when the webhook was sent
`X-Marketplace-Id`	Yes	Your marketplace ID
`X-Marketplace-Event-Id`	No	Unique idempotency key for the event

Signature Generation

Generate the signature using HMAC-SHA256:

payload = "<timestamp>.<JSON_body>"
signature = "sha256=" + HMAC-SHA256(your_api_secret, payload)

TypeScript implementation:

Bash implementation:

Timestamp tolerance: The timestamp must be within 5 minutes (300 seconds) of the current server time.

Inbound Event Types

Event	Description
`repayment.deducted`	A repayment was successfully deducted from a merchant's sale/settlement
`repayment.failed`	A repayment deduction attempt failed
`repayment.reversed`	A previously deducted repayment was reversed
`settlement.created`	A settlement batch was created containing repayment deductions
`settlement.transferred`	A settlement was transferred via bank transfer

Example — repayment.deducted

{
  "event": "repayment.deducted",
  "event_id": "evt_rep_001",
  "timestamp": "2026-01-29T10:30:00.000Z",
  "marketplace": {
    "id": "marketplace_uuid",
    "name": "Your Marketplace"
  },
  "merchant": {
    "marketplace_id": "your_internal_merchant_id",
    "opensylo_id": "opensylo_merchant_uuid"
  },
  "loan": {
    "opensylo_id": "loan_uuid",
    "opensylo_reference": "LOAN-2026-001"
  },
  "deduction": {
    "reference": "deduct_ref_001",
    "amount": 5000,
    "currency": "NGN",
    "deducted_at": "2026-01-29T10:30:00.000Z"
  },
  "source_transaction": {
    "id": "order_123",
    "type": "sale",
    "gross_amount": 25000,
    "timestamp": "2026-01-29T10:25:00.000Z"
  },
  "loan_balance": {
    "total_due": 100000,
    "total_paid": 55000,
    "outstanding": 45000
  }
}

Webhook Response

OpenSylo responds with an acknowledgment:

{
  "status": "received",
  "event_id": "evt_rep_001",
  "opensylo_reference": "txn_uuid",
  "received_at": "2026-01-29T10:30:01.000Z"
}

Outbound Webhooks (OpenSylo to Marketplace)

OpenSylo sends webhooks to your configured webhook URL to notify you of loan lifecycle events.

Verification

When receiving a webhook from OpenSylo, verify the signature using the same HMAC-SHA256 method described above, but using OpenSylo's webhook secret (provided during marketplace setup).

Outbound Event Types

Event	Description
`loan.approved`	A loan has been approved for one of your merchants. Includes loan terms, repayment terms, and optional repayment schedule.
`loan.disbursed`	Loan funds have been disbursed to the merchant. Includes disbursement details and repayment start date. Start deducting repayments.
`loan.repayment_updated`	Repayment terms have changed (deduction percentage, due date). Update your deduction logic.
`loan.nearly_complete`	Loan is close to full repayment (>90% paid). Includes `max_deduction_amount` — cap the next deduction to avoid overpayment.
`loan.completed`	Loan is fully repaid. Stop all deductions immediately.
`loan.defaulted`	Loan has defaulted. Includes `collection_instructions` with priority level.

Example — loan.approved

{
  "event": "loan.approved",
  "event_id": "evt_loan_001",
  "timestamp": "2026-01-29T14:00:00.000Z",
  "loan": {
    "id": "loan_uuid",
    "reference": "LOAN-2026-001",
    "status": "APPROVED"
  },
  "merchant": {
    "opensylo_id": "merchant_uuid",
    "marketplace_id": "your_internal_merchant_id"
  },
  "lender": {
    "id": "lender_uuid",
    "name": "FinCo Lending"
  },
  "terms": {
    "principal_amount": 500000,
    "interest_rate": 5.0,
    "tenor_days": 90,
    "total_repayment": 525000,
    "currency": "NGN"
  },
  "repayment": {
    "method": "sales_deduction",
    "deduction_percentage": 10,
    "minimum_deduction": 500,
    "start_date": "2026-02-01T00:00:00.000Z",
    "due_date": "2026-05-01T00:00:00.000Z"
  },
  "schedule": [
    { "installment": 1, "due_date": "2026-02-01", "amount": 175000 },
    { "installment": 2, "due_date": "2026-03-01", "amount": 175000 },
    { "installment": 3, "due_date": "2026-04-01", "amount": 175000 }
  ]
}

Example — loan.completed

{
  "event": "loan.completed",
  "event_id": "evt_loan_005",
  "timestamp": "2026-04-15T09:00:00.000Z",
  "loan": {
    "id": "loan_uuid",
    "reference": "LOAN-2026-001",
    "status": "REPAID"
  },
  "merchant": {
    "opensylo_id": "merchant_uuid",
    "marketplace_id": "your_internal_merchant_id"
  },
  "summary": {
    "principal_repaid": 500000,
    "interest_repaid": 25000,
    "total_repaid": 525000,
    "total_deductions": 42,
    "first_deduction_at": "2026-02-01T10:00:00.000Z",
    "final_deduction_at": "2026-04-15T08:55:00.000Z",
    "completed_at": "2026-04-15T09:00:00.000Z"
  },
  "action_required": "stop_deductions",
  "message": "Loan fully repaid. Stop all deductions for this loan immediately."
}

Retry Policy

OpenSylo retries failed webhook deliveries with exponential backoff:

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

After 5 failed attempts, the webhook is marked as failed. Your webhook endpoint should return a 2xx status code to acknowledge receipt.

Webhook Headers Reference

Header	Direction	Description
`X-Marketplace-Signature`	Inbound (you to OpenSylo)	`sha256=` + HMAC-SHA256 hex digest
`X-Marketplace-Timestamp`	Inbound (you to OpenSylo)	Unix timestamp in seconds
`X-Marketplace-Id`	Inbound (you to OpenSylo)	Your marketplace UUID
`X-Marketplace-Event-Id`	Inbound (you to OpenSylo)	Idempotency key (optional)

Signature Formula

payload = "<unix_timestamp>.<JSON.stringify(body)>"
signature = "sha256=" + HMAC_SHA256(api_secret, payload).hexdigest()

Inbound Webhooks (Marketplace to OpenSylo)#

Endpoints#

Required Headers#

Signature Generation#

Inbound Event Types#

Example — repayment.deducted#

Webhook Response#

Outbound Webhooks (OpenSylo to Marketplace)#

Verification#

Outbound Event Types#

Example — loan.approved#

Example — loan.completed#

Retry Policy#

Webhook Headers Reference#

Signature Formula#