config-webhook

Configure Webhook Subscription

Before receiving webhooks, you need to register your webhook URL.

Endpoint

POST /apps/api/webhooks

Headers:

Authorization: Bearer {access_token}
Content-Type: application/json

Request Body

{
  "webhookUrl": "https://yourdomain.com/webhooks/wepay"
}

Field Descriptions

Field	Type	Required?	Description
webhookUrl	String	Yes	Your HTTPS endpoint URL to receive webhook notifications. Must be publicly accessible. Example: https://api.yoursite.com/webhooks

Example Request (cURL)

curl -X POST "https://api.wepay.com.sa/apps/api/webhooks" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "webhookUrl": "https://yourdomain.com/webhooks/wepay"
  }'

Example Response

{
  "data": {
    "id": "019bb692-28e0-7ae1-926f-59b12c3b784c",
    "webhookUrl": "https://yourdomain.com/webhooks/wepay",
    "secretKey": "whsec_abc123xyz789defghijklmnopqrstuvwxyz",
    "isActive": true,
    "consecutiveFailures": 0,
    "lastSuccessAt": null,
    "lastFailureAt": null,
    "createdAt": "2026-01-19T12:00:00Z"
  },
  "message": "Webhook created successfully.",
  "status": 200,
  "validationErrors": []
}

Response Fields

Field	Description
id	Your business entity ID (used as webhook subscription identifier)
webhookUrl	Your registered webhook endpoint
secretKey	Secret key for signature verification (Save this securely)
isActive	Whether the webhook is currently active (false if disabled due to failures)
consecutiveFailures	Number of consecutive delivery failures (resets to 0 on success)
lastSuccessAt	Timestamp of last successful delivery
lastFailureAt	Timestamp of last failed delivery
createdAt	When the business entity was created

Important: Save the secretKey securely. You'll need it to verify webhook signatures. The secret is only shown once when creating or regenerating. Never expose your secret key in client-side code.

---

Get Webhook Subscription

Retrieve your current webhook configuration.

Endpoint

GET /apps/api/webhooks

Headers:

Authorization: Bearer {access_token}

Example Request (cURL)

curl -X GET "https://api.wepay.com.sa/apps/api/webhooks" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Example Response

{
  "data": {
    "id": "019bb692-28e0-7ae1-926f-59b12c3b784c",
    "webhookUrl": "https://yourdomain.com/webhooks/wepay",
    "secretKey": "whsec_abc123xyz789defghijklmnopqrstuvwxyz",
    "isActive": true,
    "consecutiveFailures": 0,
    "lastSuccessAt": "2026-01-19T14:30:00Z",
    "lastFailureAt": null,
    "createdAt": "2026-01-19T12:00:00Z"
  },
  "message": "",
  "status": 200,
  "validationErrors": []
}

---

Update Webhook URL

Update your existing webhook subscription with a new URL.

Endpoint

POST /apps/api/webhooks

Headers:

Authorization: Bearer {access_token}
Content-Type: application/json

Request Body

{
  "webhookUrl": "https://newdomain.com/webhooks/wepay"
}

Example Request (cURL)

curl -X POST "https://api.wepay.com.sa/apps/api/webhooks" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "webhookUrl": "https://newdomain.com/webhooks/wepay"
  }'

Example Response

{
  "data": {
    "id": "019bb692-28e0-7ae1-926f-59b12c3b784c",
    "webhookUrl": "https://newdomain.com/webhooks/wepay",
    "secretKey": "whsec_abc123xyz789defghijklmnopqrstuvwxyz",
    "isActive": true,
    "consecutiveFailures": 0,
    "lastSuccessAt": "2026-01-19T14:30:00Z",
    "lastFailureAt": null,
    "createdAt": "2026-01-19T12:00:00Z"
  },
  "message": "Webhook updated successfully.",
  "status": 200,
  "validationErrors": []
}

Note: Updating the webhook URL also re-enables the subscription if it was disabled due to consecutive failures.

---

Regenerate Secret Key

If your secret key is compromised, regenerate it immediately.

Endpoint

POST /apps/api/webhooks/regenerate-secret

Headers:

Authorization: Bearer {access_token}

Example Request (cURL)

curl -X POST "https://api.wepay.com.sa/apps/api/webhooks/regenerate-secret" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Example Response

{
  "data": {
    "secretKey": "whsec_xYz123AbCdEfGhIjKlMnOpQrStUvWxYz456"
  },
  "message": "Webhook secret regenerated successfully.",
  "status": 200,
  "validationErrors": []
}

Important: After regenerating, update your server immediately to use the new secret key. Webhooks signed with the old key will fail verification.

---