--- title: Subscribe to new Webhook slug: api/subscribe-to-new-webhook docTags: createdAt: 2026-09-20T23:41:11.143Z --- { "id": "Y0CK4kJ0n_kOuePC6-VM8", "type": "api-oas-v2", "data": { "method": "POST", "url": "https://api.mpay.com.au/subscriptions/v1/create", "servers": [ { "url": "https://api.mpay.com.au/subscriptions/v1/create", "description": "Production URL" }, { "url": "https://api.m-pay.com.au/subscriptions/v1/create", "description": "Sandbox URL" } ], "name": "Subscribe to new Webhook", "description": "Adds a new URL to which callbacks will be sent.", "contentType": "application/json", "request": { "pathParameters": [], "headerParameters": [ { "name": "accept", "type": "string", "kind": "optional", "description": "Generated from available response content types", "enum": [ "application/json" ], "default": "application/json" } ], "queryParameters": [], "bodyDataParameters": [ { "kind": "required", "name": "body", "type": "object", "description": "", "customType": "subscriptionCreateRequest_V1", "schema": [ { "name": "eventName", "kind": "required", "type": "string", "description": "

Required. The type of event to be sent to this URL via callback. Must be one of the supported event names listed below.

", "example": "NPPReceivePayment", "default": "NPPReceivePayment", "enum": [ "DirectDebitClearance", "DirectEntryDishonour", "InboundDirectCredit", "InboundDirectCreditRejections", "InboundDirectDebit", "InboundRtgsImtStatus", "InternationalNPPReceivePayment", "InternationalNppPaymentReturn", "InternationalNppPaymentStatus", "MTPTransactionNotification", "NPPCreditRejections", "NPPReceivePayment", "NppPaymentStatus", "NppReturn", "PayToReceivePayment", "PendingInboundRtgsImt" ], "pattern": "^(DirectDebitClearance|DirectEntryDishonour|InboundDirectCredit|InboundDirectCreditRejections|InboundDirectDebit|InboundRtgsImtStatus|InternationalNPPReceivePayment|InternationalNppPaymentReturn|InternationalNppPaymentStatus|MTPTransactionNotification|NPPCreditRejections|NPPReceivePayment|NppPaymentStatus|NppReturn|PayToReceivePayment|PendingInboundRtgsImt)$" }, { "name": "targetUrl", "kind": "required", "type": "string", "description": "

Required. This is the API endpoint where the call back notification will be sent. The URL must be publicly reachable and accept POST requests; HTTPS is strongly recommended.

", "example": "https://api.yourcompany.com/monoova/callbacks", "default": "https://api.yourcompany.com/monoova/callbacks", "format": "uri", "pattern": "^https?://[^\\s]+$" }, { "name": "subscriptionStatus", "kind": "optional", "type": "string", "description": "

Optional. Determines whether callbacks are sent as soon as the subscription is created. On/Off. Defaults to Off, so send 'On' if you want the subscription to be active immediately.

", "example": "On", "default": "On", "enum": [ "On", "Off" ], "pattern": "^(On|Off)$" }, { "name": "securityToken", "kind": "optional", "type": "string", "description": "

Conditional. Required when your callback endpoint expects an Authorization header. This token will be sent back with the callback in Authorization header. (Authorization: [type] [credentials] (e.x Basic Rjc1234567890jdGMS67890U78...)) When creating the token, both 'type' and 'credentials' are required.

", "example": "Basic Rjc1234567890jdGMS67890U78", "default": "Basic Rjc1234567890jdGMS67890U78", "pattern": "^[A-Za-z]+\\s\\S+$" } ], "modelRef": "#/components/schemas/subscriptionCreateRequest_V1", "isExpanded": true } ], "formDataParameters": [], "oAuthParameters": [ { "id": "basicAuth", "name": "basicAuth", "kind": "optional", "type": "http", "description": "

To authenticate using basic authentication, generate an API key and pass it as the username. No password is required.

", "scheme": "basic" } ], "cookieParameters": [] }, "responses": [ { "statusCode": "200", "description": "Success. The subscription was created and the details of the new subscription are returned.", "jsonExample": "", "isExpanded": true, "schema": [ { "kind": "optional", "type": "object", "description": "", "customType": "subscriptionCreateResponse_V1", "schema": [ { "name": "id", "kind": "optional", "type": "integer", "description": "Unique id for the subscription. Quote this value when calling the update or delete endpoints.", "example": 10241, "default": 10241, "pattern": "^[0-9]{1,10}$" }, { "name": "dateTime", "kind": "optional", "type": "string", "description": "Date time the subscription was last updated.", "example": "2026-09-18T15:43:18.123", "default": "2026-09-18T15:43:18.123", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(\\.\\d+)?$" }, { "name": "eventName", "kind": "optional", "type": "string", "description": "The type of event to be sent to this URL via callback.", "example": "NPPReceivePayment", "default": "NPPReceivePayment", "pattern": "^(DirectDebitClearance|DirectEntryDishonour|InboundDirectCredit|InboundDirectCreditRejections|InboundDirectDebit|InboundRtgsImtStatus|InternationalNPPReceivePayment|InternationalNppPaymentReturn|InternationalNppPaymentStatus|MTPTransactionNotification|NPPCreditRejections|NPPReceivePayment|NppPaymentStatus|NppReturn|PayToReceivePayment|PendingInboundRtgsImt)$" }, { "name": "targetUrl", "kind": "optional", "type": "string", "description": "This is the API endpoint where the call back notification will be sent.", "example": "https://api.yourcompany.com/monoova/callbacks", "default": "https://api.yourcompany.com/monoova/callbacks", "format": "uri", "pattern": "^https?://[^\\s]+$" }, { "name": "durationMs", "kind": "optional", "type": "integer", "description": "This value represents the total time in milliseconds that the Platform took to process the request.", "example": 128, "default": 128, "pattern": "^[0-9]{1,7}$" }, { "name": "status", "kind": "optional", "type": "string", "description": "This is the status of the request. A code of 'Ok' indicates no errors.", "example": "Ok", "default": "Ok", "pattern": "^[A-Za-z]{2,30}$" }, { "name": "statusDescription", "kind": "optional", "type": "string", "description": "

This is a description of the status. If an 'Ok' status is returned, then this will be 'Operation completed successfully'.

", "example": "Operation completed successfully", "default": "Operation completed successfully", "pattern": "^.{1,500}$" } ], "modelRef": "#/components/schemas/subscriptionCreateResponse_V1", "isExpanded": true } ] }, { "statusCode": "400", "description": "

Bad request. The request could not be processed because one or more fields are missing, malformed, or failed validation. Check the statusDescription for the field at fault, correct it and retry.

", "jsonExample": "", "isExpanded": true, "schema": [ { "kind": "optional", "type": "object", "example": "{\"durationMs\":12,\"status\":\"Error\",\"statusDescription\":\"Validation failed: targetUrl is required and must be a valid URL.\"}", "description": "

Standard error envelope returned for 400, 401 and 500 responses.

", "customType": "errorResponse", "schema": [ { "name": "durationMs", "kind": "optional", "type": "integer", "description": "This value represents the total time in milliseconds that the Platform took to process the request.", "example": 12, "default": 12, "pattern": "^[0-9]{1,7}$" }, { "name": "status", "kind": "optional", "type": "string", "description": "

This is the status of the request. A code of 'Ok' indicates no errors. For an error response this will be a failure code such as 'Error', 'Unauthorized' or 'Exception'.

", "example": "Error", "default": "Error", "pattern": "^[A-Za-z]{2,30}$" }, { "name": "statusDescription", "kind": "optional", "type": "string", "description": "

This is a description of the status. For an error response this explains what failed and, where possible, names the field at fault.

", "example": "Validation failed: targetUrl is required and must be a valid URL.", "default": "Validation failed: targetUrl is required and must be a valid URL.", "pattern": "^.{1,500}$" } ], "modelRef": "#/components/schemas/errorResponse", "isExpanded": true } ] }, { "statusCode": "401", "description": "

Unauthorized. The request did not include valid basic authentication credentials, or the API key supplied is inactive or not permitted to use this endpoint. Confirm the API key is passed as the basic authentication username and retry.

", "jsonExample": "", "isExpanded": true, "schema": [ { "kind": "optional", "type": "object", "example": "{\"durationMs\":4,\"status\":\"Unauthorized\",\"statusDescription\":\"Authentication failed. Check the API key supplied as the username.\"}", "description": "

Standard error envelope returned for 400, 401 and 500 responses.

", "customType": "errorResponse", "schema": [ { "name": "durationMs", "kind": "optional", "type": "integer", "description": "This value represents the total time in milliseconds that the Platform took to process the request.", "example": 12, "default": 12, "pattern": "^[0-9]{1,7}$" }, { "name": "status", "kind": "optional", "type": "string", "description": "

This is the status of the request. A code of 'Ok' indicates no errors. For an error response this will be a failure code such as 'Error', 'Unauthorized' or 'Exception'.

", "example": "Error", "default": "Error", "pattern": "^[A-Za-z]{2,30}$" }, { "name": "statusDescription", "kind": "optional", "type": "string", "description": "

This is a description of the status. For an error response this explains what failed and, where possible, names the field at fault.

", "example": "Validation failed: targetUrl is required and must be a valid URL.", "default": "Validation failed: targetUrl is required and must be a valid URL.", "pattern": "^.{1,500}$" } ], "modelRef": "#/components/schemas/errorResponse", "isExpanded": true } ] }, { "statusCode": "500", "description": "

Internal server error. An unexpected error occurred while processing the request. The request may not have been completed — do not assume the subscription changed. Retry the request and, if the error persists, contact Monoova support quoting the statusDescription.

", "jsonExample": "", "isExpanded": true, "schema": [ { "kind": "optional", "type": "object", "example": "{\"durationMs\":5312,\"status\":\"Exception\",\"statusDescription\":\"An unexpected error occurred while processing the request. Please contact Monoova support.\"}", "description": "

Standard error envelope returned for 400, 401 and 500 responses.

", "customType": "errorResponse", "schema": [ { "name": "durationMs", "kind": "optional", "type": "integer", "description": "This value represents the total time in milliseconds that the Platform took to process the request.", "example": 12, "default": 12, "pattern": "^[0-9]{1,7}$" }, { "name": "status", "kind": "optional", "type": "string", "description": "

This is the status of the request. A code of 'Ok' indicates no errors. For an error response this will be a failure code such as 'Error', 'Unauthorized' or 'Exception'.

", "example": "Error", "default": "Error", "pattern": "^[A-Za-z]{2,30}$" }, { "name": "statusDescription", "kind": "optional", "type": "string", "description": "

This is a description of the status. For an error response this explains what failed and, where possible, names the field at fault.

", "example": "Validation failed: targetUrl is required and must be a valid URL.", "default": "Validation failed: targetUrl is required and must be a valid URL.", "pattern": "^.{1,500}$" } ], "modelRef": "#/components/schemas/errorResponse", "isExpanded": true } ] } ], "hasXCodeSamples": false, "examples": { "languages": [ { "id": "oVYR-hRb9NjVy4AOwVMcg", "language": "curl", "label": "cURL", "code": "curl --request POST \\\n --url https://api.mpay.com.au/subscriptions/v1/create \\\n --header 'accept: application/json' \\\n --header 'content-type: application/json' \\\n --data '{\n \"eventName\": \"NPPReceivePayment\",\n \"targetUrl\": \"https://api.yourcompany.com/monoova/callbacks\",\n \"subscriptionStatus\": \"On\",\n \"securityToken\": \"Basic Rjc1234567890jdGMS67890U78\"\n }'" }, { "id": "PFX9Q4rinzPUH8q1NTYya", "language": "javascript", "label": "javascript", "code": "var myHeaders = new Headers();\nmyHeaders.append(\"accept\", \"application/json\");\nmyHeaders.append(\"content-type\", \"application/json\");\n\nvar raw = JSON.stringify({\n \"eventName\": \"NPPReceivePayment\",\n \"targetUrl\": \"https://api.yourcompany.com/monoova/callbacks\",\n \"subscriptionStatus\": \"On\",\n \"securityToken\": \"Basic Rjc1234567890jdGMS67890U78\"\n});\n\nvar requestOptions = {\n method: 'POST',\n headers: myHeaders,\n body: raw,\n redirect: 'follow'\n};\n\nfetch(\"https://api.mpay.com.au/subscriptions/v1/create\", requestOptions)\n .then(response => response.text())\n .then(result => console.log(result))\n .catch(error => console.log('error', error));" }, { "id": "yDdE5HEbCVhH7fhkzpsqQ", "language": "ruby", "label": "Ruby", "code": "require \"uri\"\nrequire \"json\"\nrequire \"net/http\"\n\nurl = URI(\"https://api.mpay.com.au/subscriptions/v1/create\")\n\nhttps = Net::HTTP.new(url.host, url.port)\nhttps.use_ssl = true\n\nrequest = Net::HTTP::Post.new(url)\nrequest[\"accept\"] = \"application/json\"\nrequest[\"content-type\"] = \"application/json\"\nrequest.body = JSON.dump({\n \"eventName\": \"NPPReceivePayment\",\n \"targetUrl\": \"https://api.yourcompany.com/monoova/callbacks\",\n \"subscriptionStatus\": \"On\",\n \"securityToken\": \"Basic Rjc1234567890jdGMS67890U78\"\n})\n\nresponse = https.request(request)\nputs response.read_body\n" }, { "id": "7w7jnnGxUhGXdkgL4Zq9j", "language": "python", "label": "Python", "code": "import requests\nimport json\n\nurl = \"https://api.mpay.com.au/subscriptions/v1/create\"\n\npayload = json.dumps({\n \"eventName\": \"NPPReceivePayment\",\n \"targetUrl\": \"https://api.yourcompany.com/monoova/callbacks\",\n \"subscriptionStatus\": \"On\",\n \"securityToken\": \"Basic Rjc1234567890jdGMS67890U78\"\n})\nheaders = {\n 'accept': 'application/json',\n 'content-type': 'application/json'\n}\n\nresponse = requests.request(\"POST\", url, headers=headers, data=payload)\n\nprint(response.text)\n" } ], "selectedLanguageId": "oVYR-hRb9NjVy4AOwVMcg" }, "results": { "languages": [ { "id": "q2Z5FmYyd0I4ORXxBvIU7", "language": "200", "code": "// Success. The subscription was created and the details of the new subscription are returned.\n{\n \"id\": 10241,\n \"dateTime\": \"2026-09-18T15:43:18.123\",\n \"eventName\": \"NPPReceivePayment\",\n \"targetUrl\": \"https://api.yourcompany.com/monoova/callbacks\",\n \"durationMs\": 128,\n \"status\": \"Ok\",\n \"statusDescription\": \"Operation completed successfully\"\n}" }, { "id": "k42931NBU0dF_ysWpHTok", "language": "400", "code": "// Bad request. The request could not be processed because one or more fields are missing, malformed, or failed validation. Check the statusDescription for the field at fault, correct it and retry.\n{\n \"durationMs\": 12,\n \"status\": \"Error\",\n \"statusDescription\": \"Validation failed: targetUrl is required and must be a valid URL.\"\n}" }, { "id": "3cP_1stM9Zd1b90PyBj0r", "language": "401", "code": "// Unauthorized. The request did not include valid basic authentication credentials, or the API key supplied is inactive or not permitted to use this endpoint. Confirm the API key is passed as the basic authentication username and retry.\n{\n \"durationMs\": 12,\n \"status\": \"Error\",\n \"statusDescription\": \"Validation failed: targetUrl is required and must be a valid URL.\"\n}" }, { "id": "lzwubEpwjIrUco1Lk2fJD", "language": "500", "code": "// Internal server error. An unexpected error occurred while processing the request. The request may not have been completed — do not assume the subscription changed. Retry the request and, if the error persists, contact Monoova support quoting the statusDescription.\n{\n \"durationMs\": 12,\n \"status\": \"Error\",\n \"statusDescription\": \"Validation failed: targetUrl is required and must be a valid URL.\"\n}" } ], "selectedLanguageId": "q2Z5FmYyd0I4ORXxBvIU7" } }, "children": [ { "text": "" } ] }