Create Callback
Use this endpoint to create a callback. You must specify details about the callback, such as the callback URL and the authentication details used to connect to the URL.
After creating a callback, it must be verified before it can be used in an event subscription.
A successful response returns the details of the callback such as the callback name, callback URL, and batch size.
Service URL:
/rest/api/v1.3/notifications/callbacks
Request Method:
POST
Request Header:
Authorization=<AUTH_TOKEN>
Content-Type=application/json
Request Body - Required Properties:
-
name
– Name of the callback to create. -
url
– URL location for the callback. Responsys must be able to connect and authenticate to this URL. -
batchSize
– Determines the maximum number of events sent in a callback. Must be positive integer. Maximum 200. -
authentication
– Authentication details used to authenticate to the callback URL. Basic authentication (B) is supported. The userName and password credentials will be used to authenticate to the callback url.
Request Body - Optional Properties:
-
backupUrl
– A back up callback URL for Responsys to call, in the event theurl
is unreachable. After 3 unsuccessful attempts at theurl
, Responsys will call the back up URL. The back up URL can be on the same domain as the primary URL, but cannot be the exact location.
Sample Request Body
{
"name": "<callback_name>",
"url": "<callback_url>",
"backupUrl ": "<backupCallbackUrl>",
"batchSize": <batch_size>,
"authentication": {
"type": "B",
"data": {
"userName": "<username>",
"password": "<password>"
}
}
}
Sample Response Body - Success
{
"name": "<callback_name>",
"url": "<callback_url>",
"backupUrl ": "<backupCallbackUrl>",
"batchSize": 1,
"links": [
{
"rel": "self",
"href": "<callback_url>",
"method": "PUT"
},
{
"rel": "getCallBack",
"href": "<callback_url>",
"method": "GET"
},
{
"rel": "deleteCallBack",
"href": "<callback_url>",
"method": "DELETE"
}
]
}
Sample Response Body - Failure
400 Bad Request
Callback already exists: Requests fail if a callback with the same name specified already exists. The error resembles:
{
"type": "",
"title": "Invalid request parameters",
"errorCode": "INVALID_PARAMETER",
"detail": "Callback with name [<callback_name>] already exists",
"errorDetails": []
}
Invalid callback URL: Requests fail if the system cannot connect to the callback URL. Error resembles:
{
"type": "",
"title": "Invalid request parameters",
"errorCode": "INVALID_PARAMETER",
"detail": "Could not connect to callback url [<callback_url> ]",
"errorDetails": []
}
URL already exists: Requests fail if a callback with the URL specified already exists. The error resembles:
{
"type": "",
"title": "Invalid request parameters",
"errorCode": "INVALID_PARAMETER",
"detail": "Callback url <callback_url> ] already exists",
"errorDetails": []
}
Invalid credentials: Requests fail if the credentials specified in the request cannot be used to connect to the URL specified. The error resembles:
{
"type": "",
"title": "Invalid request parameters",
"errorCode": "INVALID_PARAMETER",
"detail": "Could not connect to callback url [<callback_url>]",
"errorDetails": []
}
Invalid authentication: Requests fail if the authentication method specified is invalid. Only Basic Authentication (B) is supported. The error resembles:
{
"type": "",
"title": "Invalid request parameters",
"errorCode": "INVALID_PARAMETER",
"detail": "Only Basic Authentication is supported currently and value should be 'B' ",
"errorDetails": []
}
Empty batch size: Requests fail if the batch size specified is less than 0. The error resembles:
{
"type": "",
"title": "Invalid request parameters",
"errorCode": "INVALID_PARAMETER",
"detail": "Batch Size cannot be less than 0",
"errorDetails": []
}
Empty callback name: Requests fail if a callback name is not specified. The error resembles:
{
"type": "",
"title": "Invalid request parameters",
"errorCode": "INVALID_PARAMETER",
"detail": "callback name cannot be empty or null",
"errorDetails": []
}
Empty URL: Requests fail if a callback URL is not specified. The error resembles:
{
"type": "",
"title": "Invalid request parameters",
"errorCode": "INVALID_PARAMETER",
"detail": "callback url cannot be empty or null",
"errorDetails": []
}
Empty authentication: Requests fail if an authentication type is not specified. The error resembles:
{
"type": "",
"title": "Invalid field name",
"errorCode": "INVALID_FIELD_NAME",
"detail": "The following field names [invalid_field_names_list] are invalid",
"errorDetails": []
}