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 the url is unreachable. After 3 unsuccessful attempts at the url, 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": []
}