As discussed in Understand event webhooks, an event webhook sends a POST request to specified URLs each time a specific event occurs (for example, when an order is submitted). The body of the request contains the data associated with the event. An external system that receives the message returns a 200-level HTTP status code if the data is received successfully. If the message is not received successfully by one or more URLs (for example, due to a network issue or an external system being down), Oracle Commerce Cloud sends the POST request again to those URLs after a specified interval, and continues resending it until it succeeds or until the specified limit on the number of attempts is reached. By default, the interval is one hour, and the maximum number of attempts is 5, but you can change these values using either the updateWebHook
or updateWebHooks
endpoint.
Messages that are not delivered successfully after the maximum number of attempts are saved for later retrieval. You can manage these failed messages by viewing them, deleting them, or resending them, using the endpoints described in the previous section.
To resend a single failed webhook message, use the updateFailedMessage
endpoint. The body of the request should set the resend
property of the failed message to true
. For example:
PUT /ccadmin/v1/webhookFailedMessages/200001 HTTP/1.1
Authorization: Bearer <access_token
>
{
"resend": true
}
Setting resend
to true
causes the message to be added to a queue for resending. If the message was originally sent to multiple URLs, the service that manages the queue ensures that the message is resent to only those URLs for which the webhook failed originally.
Retrieve multiple failed messages
You can use the getFailedMessages
endpoint to view all of the failed messages that have been stored. However, there may be a large number of messages, so you may find it desirable to return only a subset of the failed messages.
You can use the q
query parameter to filter the set of messages to return, based on values of the message properties. Typically you would filter based on serverType
(production
or publishing
) or messageType
. For example, the following call returns only those failed messages whose messageType
is atg.commerce.fulfillment.SubmitOrder
:
GET /ccadmin/v1/webhookFailedMessages?q=messageType=
"atg.commerce.fulfillment.SubmitOrder" HTTP/1.1
Authorization: Bearer <access_token>
You can also filter messages by when they were saved. For example, to return messages that were saved after a specific time:
GET /ccadmin/v1/webhookFailedMessages?q=savedTime > "2016-04-11T02:41:00.000Z"
HTTP/1.1
Authorization: Bearer <access_token>
Resend multiple failed messages
To resend failed messages, you can either specify them individually using the updateFailedMessage
endpoint, or use the updateFailedMessages
endpoint to queue all of the stored messages for resending. You can also use the q
parameter with the updateFailedMessages
endpoint to specify a subset of the stored messages for resending. Note, however, the format of filter expressions for this parameter is different from the format used for the getFailedMessages
endpoint. With updateFailedMessages
, the q
parameter accepts expressions in SCIM format, as discussed in the REST API query parameters section.
For example, the following call adds the failed production messages to the queue for resending:
PUT /ccadmin/v1/webhookFailedMessages?q=serverType eq "production" HTTP/1.1 Authorization: Bearer<access_token>
{ "resend": true }
The following call adds only the production messages that were saved after a specific time:
PUT /ccadmin/v1/webhookFailedMessages?q=serverType eq "production" and savedTime gt "2016-04-11T02:41:00.000Z" HTTP/1.1 Authorization: Bearer<access_token>
{ "resend": true }