Register Webhook
Create or update webhook callback endpoints for merchant event notifications.
Error Codes
| Code | Status | Reason | What to do |
|---|---|---|---|
| VALIDATION_ERROR | 422 | Webhook payload is invalid | Ensure all webhook URLs and auth key values are valid. |
/api/public/webhooksRegister Webhook
Create or update webhook callback endpoints for merchant event notifications.
Error Codes
| Code | Status | Reason | What to do |
|---|---|---|---|
| VALIDATION_ERROR | 422 | Webhook payload is invalid | Ensure all webhook URLs and auth key values are valid. |
Servers
Staging: https://dev-api.shabaas.com
Production: https://api.shabaas.com
Authentication
Authorization: Bearer <token>Bearer token returned by /api/public/authorization.
Request Body
Requiredapplication/jsonRequest payload to create or update merchant webhook endpoints.
Properties
auth_keyRequiredstringShared secret value sent with webhook requests for receiver-side verification.
"whsec_7f9d2b84c1f2"payment_agreementRequiredstringHTTPS endpoint that receives payment agreement status callbacks.
"https://staging.abc.co/payment_agreement"payment_initiationRequiredstringHTTPS endpoint that receives payment initiation callbacks.
"https://staging.abc.co/payment_initiation"direct_debit_acceptedRequiredstringHTTPS endpoint invoked when direct debit is accepted.
"https://staging.abc.co/direct_debit_accepted"direct_debit_rejectedRequiredstringHTTPS endpoint invoked when direct debit is rejected/dishonoured.
"https://staging.abc.co/direct_debit_rejected"Save all webhook endpoints
{
"auth_key": "whsec_7f9d2b84c1f2",
"payment_agreement": "https://staging.abc.co/payment_agreement",
"payment_initiation": "https://staging.abc.co/payment_initiation",
"direct_debit_accepted": "https://staging.abc.co/direct_debit_accepted",
"direct_debit_rejected": "https://staging.abc.co/direct_debit_rejected"
}Responses
200Webhook endpoints saved successfully.
application/jsonProperties
messageOptionalstring"Success"dataOptionalobjectAdditional properties are supported; see the endpoint definition for their schema.
Webhook configuration saved
{
"message": "Webhook saved successfully",
"data": {}
}422Invalid webhook payload (missing fields or invalid URLs).
application/jsonProperties
messageRequiredstring"Payee account cannot receive NPP Payments"error_codeRequiredstring"MOV_NPP_PAYMENT_NOT_SUPPORTED"dataRequiredobject{
"response_time": "2026-04-08T12:28:26.759Z"
}Additional properties are supported; see the endpoint definition for their schema.
Invalid webhook body
{
"message": "Validation failed",
"error_code": "VALIDATION_ERROR",
"data": {
"response_time": "2026-04-29T08:00:00.000Z"
}
}Full endpoint OpenAPI definition
{
"openapi": "3.0.3",
"info": {
"title": "ShaBaasPay Public API",
"version": "1.0.0",
"description": "Describes public REST endpoints for authorization, payment agreements, payment initiations,\nrefunds, webhooks, and PayID collection APIs.\n"
},
"servers": [
{
"url": "https://dev-api.shabaas.com",
"description": "Staging"
},
{
"url": "https://api.shabaas.com",
"description": "Production"
}
],
"tags": [
{
"name": "Webhooks",
"x-displayName": "Webhooks",
"description": "Configure notification endpoints for agreement and payment events."
}
],
"x-tagGroups": [
{
"name": "SHABAASPAY PUBLIC API",
"tags": [
"API Keys",
"Payment Agreement",
"Payment Initiation",
"Checkout",
"B2B Collections",
"Webhooks"
]
},
{
"name": "Internal",
"tags": [
"Clients"
]
}
],
"security": [
{
"BearerAuth": []
}
],
"paths": {
"/api/public/webhooks": {
"post": {
"tags": [
"Webhooks"
],
"summary": "Register Webhook",
"description": "Create or update webhook callback endpoints for merchant event notifications.\n\n### Error Codes\n| Code | Status | Reason | What to do |\n| ---- | ------ | ------ | ---------- |\n| VALIDATION_ERROR | 422 | Webhook payload is invalid | Ensure all webhook URLs and auth key values are valid. |\n",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/WebhookUpsertRequest"
},
"examples": {
"upsert_webhooks": {
"summary": "Save all webhook endpoints",
"value": {
"auth_key": "whsec_7f9d2b84c1f2",
"payment_agreement": "https://staging.abc.co/payment_agreement",
"payment_initiation": "https://staging.abc.co/payment_initiation",
"direct_debit_accepted": "https://staging.abc.co/direct_debit_accepted",
"direct_debit_rejected": "https://staging.abc.co/direct_debit_rejected"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Webhook endpoints saved successfully.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/MessageResponse"
},
"examples": {
"saved": {
"summary": "Webhook configuration saved",
"value": {
"message": "Webhook saved successfully",
"data": {}
}
}
}
}
}
},
"422": {
"description": "Invalid webhook payload (missing fields or invalid URLs).",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
},
"examples": {
"invalid_payload": {
"summary": "Invalid webhook body",
"value": {
"message": "Validation failed",
"error_code": "VALIDATION_ERROR",
"data": {
"response_time": "2026-04-29T08:00:00.000Z"
}
}
}
}
}
}
}
}
}
}
},
"components": {
"schemas": {
"WebhookUpsertRequest": {
"type": "object",
"description": "Request payload to create or update merchant webhook endpoints.",
"required": [
"auth_key",
"payment_agreement",
"payment_initiation",
"direct_debit_accepted",
"direct_debit_rejected"
],
"properties": {
"auth_key": {
"type": "string",
"description": "Shared secret value sent with webhook requests for receiver-side verification.",
"minLength": 8,
"maxLength": 200,
"example": "whsec_7f9d2b84c1f2"
},
"payment_agreement": {
"type": "string",
"format": "uri",
"description": "HTTPS endpoint that receives payment agreement status callbacks.",
"example": "https://staging.abc.co/payment_agreement"
},
"payment_initiation": {
"type": "string",
"format": "uri",
"description": "HTTPS endpoint that receives payment initiation callbacks.",
"example": "https://staging.abc.co/payment_initiation"
},
"direct_debit_accepted": {
"type": "string",
"format": "uri",
"description": "HTTPS endpoint invoked when direct debit is accepted.",
"example": "https://staging.abc.co/direct_debit_accepted"
},
"direct_debit_rejected": {
"type": "string",
"format": "uri",
"description": "HTTPS endpoint invoked when direct debit is rejected/dishonoured.",
"example": "https://staging.abc.co/direct_debit_rejected"
}
}
},
"MessageResponse": {
"type": "object",
"properties": {
"message": {
"type": "string",
"example": "Success"
},
"data": {
"type": "object",
"additionalProperties": true
}
}
},
"ErrorResponse": {
"type": "object",
"required": [
"message",
"error_code",
"data"
],
"properties": {
"message": {
"type": "string",
"example": "Payee account cannot receive NPP Payments"
},
"error_code": {
"type": "string",
"example": "MOV_NPP_PAYMENT_NOT_SUPPORTED"
},
"data": {
"type": "object",
"additionalProperties": true,
"example": {
"response_time": "2026-04-08T12:28:26.759Z"
}
}
}
}
},
"securitySchemes": {
"BearerAuth": {
"type": "http",
"scheme": "bearer",
"bearerFormat": "JWT",
"description": "Bearer token returned by `/api/public/authorization`."
}
}
}
}