Webhooks

Webhook endpoints receive HTTP POST notifications when payment events occur. Register one or more endpoints and subscribe to the event types you care about. See the Webhooks guide for signature verification and best practices.

Register a webhook

POST

/v1/webhooks

ℹ️Your webhook secret for signature verification is set at the merchant level in the dashboard. See Verifying signatures.

Body parameters

urlstringrequired

HTTPS URL that will receive webhook POST requests. HTTP URLs are rejected.

eventsarrayrequired

List of event types to subscribe to.One of: payment.confirmed, payment.expired, payment.underpaid, payment.frozen, withdrawal.completed, withdrawal.failed

Returns Returns the Webhook object.

Request

bash

curl -X POST https://api.mpchat.com/v1/webhooks \
  -H "Authorization: Bearer mk_live_abc:{ts}:{sig}" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://acme.com/webhooks/mp",
    "events": [
      "payment.confirmed",
      "payment.expired",
      "withdrawal.completed"
    ]
  }'

Response 201

JSON

{
  "id": "wh_01HQ8ZTXV...",
  "merchant_id": "a1b2c3d4-...",
  "url": "https://acme.com/webhooks/mp",
  "events": [
    "payment.confirmed",
    "payment.expired",
    "withdrawal.completed"
  ],
  "is_active": true,
  "created_at": "2024-01-15T10:00:00Z",
  "updated_at": "2024-01-15T10:00:00Z"
}

List webhooks

GET

/v1/webhooks

Return all registered webhook endpoints

No parameters.

Returns Returns an array of Webhook objects.

Request

bash

curl https://api.mpchat.com/v1/webhooks \
  -H "Authorization: Bearer mk_live_abc:{ts}:{sig}"

Response 200

JSON

[
  {
    "id": "wh_01HQ8ZTXV...",
    "merchant_id": "a1b2c3d4-...",
    "url": "https://acme.com/webhooks/mp",
    "events": ["payment.confirmed", "payment.expired"],
    "is_active": true,
    "created_at": "2024-01-15T10:00:00Z",
    "updated_at": "2024-01-15T10:00:00Z"
  }
]

List webhook deliveries

GET

/v1/webhooks/{id}/deliveries

List delivery attempts for a webhook endpoint

Path parameters

idstringrequired

The webhook endpoint UUID.

Query parameters

limitintegeroptionaldefault: 20

Maximum deliveries to return. Max 100.

offsetintegeroptionaldefault: 0

Number of deliveries to skip.

Returns Returns an object with a deliveries array and total count. Use this to diagnose failed deliveries.

Request

bash

curl "https://api.mpchat.com/v1/webhooks/wh_01HQ.../deliveries?limit=20" \
  -H "Authorization: Bearer mk_live_abc:{ts}:{sig}"

Response 200

JSON

{
  "deliveries": [
    {
      "id": "wd_01HQ...",
      "webhook_id": "wh_01HQ8ZTXV...",
      "event_type": "payment.confirmed",
      "payload": {
        "event": "payment.confirmed",
        "data": {"order_id": "c3d4e5f6-...", "status": "PAID"}
      },
      "status": "DELIVERED",
      "attempts": 1,
      "max_attempts": 6,
      "last_error": null,
      "delivered_at": "2024-01-15T10:05:03Z",
      "created_at": "2024-01-15T10:05:01Z"
    }
  ],
  "total": 14
}

Next: Withdrawals API