Configure Webhooks

Sets up webhook endpoints to receive real-time notifications for various events on your merchant account.

Authentication required (API Key or User JWT).

POST/api/merchants/:merchantId/webhooks

Authentication

This endpoint requires either:

• API Key (for server-side configuration)
• User JWT token (for admin panel configuration)

// Using API Key
Authorization: Bearer sk_test_xxxxx

// Using JWT
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Path Parameters

Parameter	Type	Description
merchantId	String	The ID of the merchant.

Request Body

Field	Type	Required	Description
url	String	Yes	The HTTPS URL that will receive webhook events.
events	Array	Yes	Array of event types to subscribe to (e.g., transaction.completed, invoice.paid).
description	String	No	Optional description of this webhook endpoint.
active	Boolean	No	Whether this webhook is active (default: true).
secret	String	No	Optional custom secret for signing webhook payloads. If not provided, one will be generated.

Example Request Body

{
  "url": "https://your-domain.com/api/skypay-webhooks",
  "events": [
    "transaction.completed",
    "transaction.failed",
    "invoice.paid",
    "payment-link.visited"
  ],
  "description": "Production webhook endpoint",
  "active": true
}

Response 201 Created

Returns the details of the created webhook configuration, including the generated secret if none was provided.

{
  "message": "Webhook configured successfully",
  "webhook": {
    "id": "whk_123456789",
    "merchantId": "merch_987654321",
    "url": "https://your-domain.com/api/skypay-webhooks",
    "events": [
      "transaction.completed",
      "transaction.failed",
      "invoice.paid",
      "payment-link.visited"
    ],
    "description": "Production webhook endpoint",
    "active": true,
    "secretKey": "whsec_xxxxxxxxxxxxxxxxxxxxxxxx", // Only returned once during creation
    "createdAt": "2023-10-26T10:00:00.000Z",
    "updatedAt": "2023-10-26T10:00:00.000Z"
  }
}

Errors

• 400 Bad Request: Invalid request body or validation failed.
• 401 Unauthorized: Invalid or missing authorization.
• 404 Not Found: Merchant not found.
• 500 Internal Server Error: Server encountered an unexpected error.

Important Security Notes

1. Store your webhook secret securely - The webhook secret is only shown once upon creation.
2. Always verify webhook signatures - Use the secret to verify that webhooks are coming from SkyPay.
3. Use HTTPS endpoints - Only HTTPS URLs are accepted for webhook endpoints.
4. Implement idempotency - Webhook events may be sent more than once in rare cases.

Example Requests

cURL

curl -X POST \
  "https://api.skypay.com/api/merchants/merch_987654321/webhooks" \
  -H "Authorization: Bearer sk_test_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-domain.com/api/skypay-webhooks",
    "events": [
      "transaction.completed",
      "transaction.failed",
      "invoice.paid"
    ],
    "description": "Production webhook endpoint"
  }'

JavaScript (Fetch API)

const webhookConfig = {
  url: "https://your-domain.com/api/skypay-webhooks",
  events: [
    "transaction.completed",
    "transaction.failed",
    "invoice.paid"
  ],
  description: "Production webhook endpoint"
};

fetch('https://api.skypay.com/api/merchants/merch_987654321/webhooks', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer sk_test_xxxxx',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(webhookConfig)
})
.then(response => response.json())
.then(data => {
  // Store the webhook secret securely!
  console.log('Webhook created with secret:', data.webhook.secretKey);
})
.catch(error => console.error('Error:', error));

Managing Webhooks

To update or delete webhook configurations, use:

• PUT /api/merchants/:merchantId/webhooks/:webhookId - Update a webhook configuration
• DELETE /api/merchants/:merchantId/webhooks/:webhookId - Delete a webhook configuration
• GET /api/merchants/:merchantId/webhooks - List all webhook configurations