Skip to main content
Meterlane uses a single webhook endpoint to receive payment lifecycle events from Circle’s Cross-Platform Network. When Circle processes a payout you initiated via POST /corridors/:id/pay, it posts a signed event payload to this URL, and Meterlane updates the corresponding payment record’s status in real time. You do not call this endpoint directly — instead, you register it as the webhook destination inside your Circle dashboard and let Circle drive the updates.

​
POST /webhooks/circle

Receives inbound payment event notifications from Circle. Meterlane verifies the Circle-Signature HMAC on every request before processing it; unauthenticated or tampered requests are rejected immediately.
Register https://corridor.meterlane.app/webhooks/circle as the webhook destination URL in your Circle dashboard. Circle will POST signed event payloads to this address whenever a payment status changes.
​
Circle-Signature
string
required
HMAC SHA-256 signature generated by Circle using your shared webhook secret. Meterlane validates this signature on every inbound request. Requests with missing or invalid signatures return 401 Unauthorized.

​
Payment events

Circle EventCorridor Payment StatusMeaning
payments.payment_completedSETTLEDFunds have been delivered to the beneficiary’s bank account
payments.payment_failedFAILEDThe payout was rejected or could not be completed
payments.compliance_holdCOMPLIANCE_HOLDPayment is paused pending a compliance review

​
Example webhook payload

Circle posts a JSON body to this endpoint. The type field identifies the event and the nested payment object carries the id that maps to a cpnPaymentId in Meterlane. 
{
  "clientId": "circle-client-id",
  "notificationType": "payments",
  "version": 1,
  "customAttributes": {
    "clientId": "circle-client-id"
  },
  "payment": {
    "id": "cpn_a1b2c3d4e5f6g7h8i9j0",
    "type": "payment",
    "status": "paid",
    "amount": {
      "amount": "100.00",
      "currency": "USD"
    },
    "updateDate": "2025-01-15T14:35:22Z"
  },
  "type": "payments.payment_completed"
}
Meterlane handles all signature verification automatically. You do not need to implement any verification logic on your end — simply ensure the Circle-Signature header is forwarded untouched if you are proxying Circle events through your own infrastructure.
A payments.compliance_hold event means the payment is paused, not permanently failed. The beneficiary has not received funds yet, and the payment may still settle or be rejected after Circle’s compliance review completes. Do not treat COMPLIANCE_HOLD as a terminal state — wait for a subsequent payments.payment_completed or payments.payment_failed event before reconciling the transaction.