Corridor Webhooks API: Circle Payment Status Events

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.

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 Event	Corridor Payment Status	Meaning
`payments.payment_completed`	`SETTLED`	Funds have been delivered to the beneficiary’s bank account
`payments.payment_failed`	`FAILED`	The payout was rejected or could not be completed
`payments.compliance_hold`	`COMPLIANCE_HOLD`	Payment 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.

Gateway API

Corridor API

Corridor Webhooks API: Circle Payment Status Events

POST /webhooks/circle

Payment events

Example webhook payload

​POST /webhooks/circle

​Payment events

​Example webhook payload

POST /webhooks/circle

Payment events

Example webhook payload