php

webhook

/webhook

Webhooks are asynchronous outbound notifications of events to an external server. For a complete description of Webhooks, please see:

Topics -> Webhooks

The Webhook resource allows for programmatic configuration of Webhooks on an UltraCart account. This document only covers the configuration of webhooks. Please consult each individual resource for details on the webhooks that a particular resource supports.

An example usage of this webhook resource is a Wordpress plugin creating a webhook so that item related events trigger webhook notifications to the Wordpress server so it can update it's local cache.

Retrieve webhooks

Permissions:
  • webhook_read

Produces: application/json
get
/webhook/webhooks

Retrieves the webhooks associated with this application.

Parameters
Parameter Description Location Data Type Required
_limit The maximum number of records to return on this one API call.
Default: 100
query integer optional
_offset Pagination of the record set. Offset is a zero based index.
Default: 0
query integer optional
_sort The sort order of the webhooks. See documentation for examples query string optional
_placeholders Whether or not placeholder values should be returned in the result. Useful for UIs that consume this REST API. query boolean optional
Responses
Status Code Reason Response Model
200
Successful response WebhooksResponse
400
Bad Request 400
401
Unauthorized 401
410
Authorized Application Disabled 410
429
Too Many Requests 429
500
Server Side 500

Add a webhook

Permissions:
  • webhook_write

Consumes: application/json
Produces: application/json
post
/webhook/webhooks

Adds a new webhook on the account. If you add a new webhook with the authentication_type set to basic, but do not specify the basic_username and basic_password, UltraCart will automatically generate random ones and return them. This allows your application to have simpler logic on the setup of a secure webhook.

Parameters
Parameter Description Location Data Type Required
webhook Webhook to create body Webhook required
_placeholders Whether or not placeholder values should be returned in the result. Useful for UIs that consume this REST API. query boolean optional
Responses
Status Code Reason Response Model
200
Successful response WebhookResponse
400
Bad Request 400
401
Unauthorized 401
410
Authorized Application Disabled 410
429
Too Many Requests 429
500
Server Side 500

Delete a webhook

Permissions:
  • webhook_write

Produces: application/json
delete
/webhook/webhooks/{webhookOid}

Delete a webhook on the UltraCart account.

Parameters
Parameter Description Location Data Type Required
webhookOid The webhook oid to delete. path integer (int32) required
Responses
Status Code Reason Response Model
204
No Content
400
Bad Request 400
401
Unauthorized 401
410
Authorized Application Disabled 410
429
Too Many Requests 429
500
Server Side 500

Update a webhook

Permissions:
  • webhook_write

Consumes: application/json
Produces: application/json
put
/webhook/webhooks/{webhookOid}

Update a webhook on the account

Parameters
Parameter Description Location Data Type Required
webhook Webhook to update body Webhook required
webhookOid The webhook oid to update. path integer (int32) required
_placeholders Whether or not placeholder values should be returned in the result. Useful for UIs that consume this REST API. query boolean optional
Responses
Status Code Reason Response Model
200
Successful response WebhookResponse
400
Bad Request 400
401
Unauthorized 401
410
Authorized Application Disabled 410
429
Too Many Requests 429
500
Server Side 500

Retrieve the log summaries

Permissions:
  • webhook_read

Produces: application/json
get
/webhook/webhooks/{webhookOid}/logs

Retrieves the log summary information for a given webhook. This is useful for displaying all the various logs that can be viewed.

Parameters
Parameter Description Location Data Type Required
webhookOid The webhook oid to retrieve log summaries for. path integer (int32) required
_limit The maximum number of records to return on this one API call.
Default: 100
query integer optional
_offset Pagination of the record set. Offset is a zero based index.
Default: 0
query integer optional
_since Fetch log summaries that have been delivered since this date/time. query dateTime optional
Responses
Status Code Reason Response Model
200
Successful response WebhookLogSummariesResponse
400
Bad Request 400
401
Unauthorized 401
410
Authorized Application Disabled 410
429
Too Many Requests 429
500
Server Side 500

Retrieve an individual log

Permissions:
  • webhook_read

Produces: application/json
get
/webhook/webhooks/{webhookOid}/logs/{requestId}

Retrieves an individual log for a webhook given the webhook oid the request id.

Parameters
Parameter Description Location Data Type Required
webhookOid The webhook oid that owns the log. path integer (int32) required
requestId The request id associated with the log to view. path string required
Responses
Status Code Reason Response Model
200
Successful response WebhookLogResponse
400
Bad Request 400
401
Unauthorized 401
410
Authorized Application Disabled 410
429
Too Many Requests 429
500
Server Side 500

Resend events to the webhook endpoint.

Permissions:
  • webhook_write

Consumes: application/json
Produces: application/json
post
/webhook/webhooks/{webhookOid}/reflow/{eventName}

This method will resend events to the webhook endpoint. This method can be used for example to send all the existing items on an account to a webhook.

Parameters
Parameter Description Location Data Type Required
webhookOid The webhook oid that is receiving the reflowed events. path integer (int32) required
eventName The event to reflow.
Allowed Values
  • item_update
path string required
Responses
Status Code Reason Response Model
200
Successful response WebhookSampleRequestResponse
400
Bad Request 400
401
Unauthorized 401
410
Authorized Application Disabled 410
429
Too Many Requests 429
500
Server Side 500

ApiUserApplicationProfile

Attributes
Name Data Type Description
api_application_logo_url string Application logo URL
application_description string Application description
application_name string Application name
developer_name string Developer name
developer_website string Developer website

Error

Attributes
Name Data Type Description
developer_message string A technical message meant to be read by a developer
error_code string HTTP status code
more_info string Additional information often a link to additional documentation
user_message string An end-user friendly message suitable for display to the customer

ErrorResponse

Attributes
Name Data Type Description
error Error Error object if unsuccessful
metadata ResponseMetadata Meta-data about the response such as payload or paging information
success boolean Indicates if API call was successful

HTTPHeader

Attributes
Name Data Type Description
name string Name of the HTTP header
value string Value of the HTTP header

ResponseMetadata

Attributes
Name Data Type Description
payload_name string Payload name
result_set ResultSet Result set

ResultSet

Attributes
Name Data Type Description
count integer (int32) Number of results in this set
limit integer (int32) Maximum number of results that can be returned in a set
more boolean True if there are more results to query
next_offset integer (int32) The next offset that you should query to retrieve more results
offset integer (int32) Offset of this result set (zero based)
total_records integer (int32) The total number of records in the result set. May be null if the number is not known and the client should continue iterating as long as more is true.

Webhook

Attributes
Name Data Type Description
api_user_oid (read only) integer (int32) Populated if webhook associated with an API user
api_version string Version of the API objects that are sent in notifications
Allowed Values
  • 2017-03-01
application_profile (read only) ApiUserApplicationProfile If associate with an application, the profile for that application
authentication_type string The type of authentication this webhook will use when communicating with your server
Allowed Values
  • none
  • basic
basic_password string Basic authentication password
basic_username string Basic authentication user name
consecutive_failures (read only) integer (int32) The number of consecutive failures that have occurred trying to deliver notifications to the target server
disabled (read only) boolean True if the webhook has been disabled
event_categories array of WebhookEventCategory The categories of events. Individual events and subscriptions are handled in the child objects. _placeholders parameter effects the population of this on a retrieval.
maximum_events integer (int32) The maximum number of events in the payload that UltraCart will deliver
maximum_size integer (int32) The maximum size of the payload that UltraCart will deliver
merchant_id (read only) string The UltraCart merchant ID that owns this webhook
next_retry_after (read only) string (dateTime) The next time UltraCart will attempt delivery if failures have been occurring
pending (read only) integer (int32) The number of pending events for this webhook
webhook_oid (read only) integer (int32) The object identifier for this webhook
webhook_url string The URL to deliver events to. Must be HTTPS for customer related information.

WebhookEventCategory

Attributes
Name Data Type Description
event_category string Name of the event category
events array of WebhookEventSubscription The events within the category. Individual subscription flags contained within the child object.
subscribed (read only) boolean True if all the events within this category are subscribed. This is a convenience flag to make user interfaces easier.

WebhookEventSubscription

Attributes
Name Data Type Description
comments (read only) string Comment about the event to provide further clarification to the end user
deprecated_flag (read only) boolean True if the event is deprecated. See the API change log for details on when it will be discontinued.
discontinued_flag (read only) boolean True if the event is discontinued. See the API change log for details on migration details.
event_description (read only) string Description of the event
event_name string Event name
expansion string The expand string for the notification object. See the individual resource _expand documentation for valid values.
subscribed boolean True if this is event is subscribed to
webhook_event_oid (read only) integer (int32) The webhook event object identifier

WebhookLog

Attributes
Name Data Type Description
delivery_dts (read only) string (dateTime) Date/time of delivery
duration (read only) integer (int32) Number of milliseconds to process the notification
request (read only) string Request payload (first 100,000 characters)
request_headers (read only) array of HTTPHeader Request headers sent to the server
request_id (read only) string Request id is a unique string that you can look up in the logs
response (read only) string Response payload (first 100,000 characters)
response_headers (read only) array of HTTPHeader Response headers received from the server
status_code (read only) integer (int32) HTTP status code received from the server
success (read only) boolean True if the delivery was successful
uri (read only) string URI of the webhook delivered to

WebhookLogResponse

Attributes
Name Data Type Description
error Error Error object if unsuccessful
metadata ResponseMetadata Meta-data about the response such as payload or paging information
success boolean Indicates if API call was successful
webhook_log WebhookLog Individual webhook log

WebhookLogSummariesResponse

Attributes
Name Data Type Description
error Error Error object if unsuccessful
metadata ResponseMetadata Meta-data about the response such as payload or paging information
success boolean Indicates if API call was successful
webhook_log_summaries array of WebhookLogSummary Webhook log summaries

WebhookLogSummary

Attributes
Name Data Type Description
delivery_dts (read only) string (dateTime) Date/time of the delivery
request_id (read only) string Request id
success (read only) boolean True if the notification was successful

WebhookResponse

Attributes
Name Data Type Description
error Error Error object if unsuccessful
metadata ResponseMetadata Meta-data about the response such as payload or paging information
success boolean Indicates if API call was successful
webhook Webhook Webhook

WebhookSampleRequest

Attributes
Name Data Type Description
request string Request
request_headers array of HTTPHeader Request headers
request_id string Request id
uri string URI to send request to

WebhookSampleRequestResponse

Attributes
Name Data Type Description
error Error Error object if unsuccessful
metadata ResponseMetadata Meta-data about the response such as payload or paging information
success boolean Indicates if API call was successful
webhook_sample_request WebhookSampleRequest The response to the sample request

WebhooksResponse

Attributes
Name Data Type Description
error Error Error object if unsuccessful
metadata ResponseMetadata Meta-data about the response such as payload or paging information
success boolean Indicates if API call was successful
webhooks array of Webhook

400
Status Code 400: bad request input such as invalid json

Headers
Name Data Type Description
UC-REST-ERROR string Contains human readable error message
Response
Name Data Type
body ErrorResponse

401
Status Code 401: invalid credentials supplied

Headers
Name Data Type Description
UC-REST-ERROR string Contains human readable error message
Response
Name Data Type
body ErrorResponse

410
Status Code 410: Your authorized application has been disabled by UltraCart

Headers
Name Data Type Description
UC-REST-ERROR string Contains human readable error message
Response
Name Data Type
body ErrorResponse

429
Status Code 429: you have exceeded the allowed API call rate limit for your application.

Headers
Name Data Type Description
UC-REST-ERROR string Contains human readable error message
Response
Name Data Type
body ErrorResponse

500
Status Code 500: any server side error. the body will contain a generic server error message

Headers
Name Data Type Description
UC-REST-ERROR string Contains human readable error message
Response
Name Data Type
body ErrorResponse