Webhooks

Webhooks allow you to get push notifications when resources change, without the need for polling. This API enables CRUD on webhooks.

Webhooks collection

GET

Retrieve list of webhooks of a specific organization.

GET /orgs/{org_pk}/webhooks/

Example request:

curl -iL --request GET "https:/www.readycloud.com/api/v2/orgs/1/webhooks/?bearer_token=4ef5b29b1f4f35c383bebfccf4bf4d01"

Response 200 (application/json):

{
  "count": 1,
  "next": null,
  "previous": null,
  "results": [
    {
      "url": "/api/v2/orgs/1/webhooks/1/",
      "remote_url": "https://example.com/catch-rc-webhook/contacts/",
      "token": "a3f7f07de894cd3c2f7f50248ccbd4",
      "created_at": "2018-03-30T08:18:48Z",
      "updated_at": "2018-03-30T08:18:48Z",
      "entity": "contact",
      "suspended_at": null
    }
  ]
}

POST

Create new webhook for a specific organization.

POST /orgs/{org_pk}/webhooks/

Allowed values for entity (default to orders):

  • ‘orders’ # for order updates, including contained resources such as boxes and items
  • ‘order-delivered’ # for order delivered events, including contained resources such as boxes and items
  • ‘packaging’ # for packaging updates
  • ‘contact’ # for contact updates, without related/dependent objects
  • ‘contact-address’ # for contact address updates, without related contact objects
  • ‘acceptance-scan’ # for order carrier acceptance scan event
  • ‘webhook’ # for webhooks (calendar) updates, global for all users, without related objects

Allowed values for remote_url: any HTTPS URL

All other properties are read-only.

Example request:

curl -iL --request POST -H "Content-Type: application/json" --upload-file data.json "https:/www.readycloud.com/api/v2/orgs/1/webhooks/?bearer_token=4ef5b29b1f4f35c383bebfccf4bf4d01"

data.json:

{
    "entity": "contact",
    "remote_url": "https://example.com/contacts/v2/"
}

Response 201 (application/json):

{
  "url": "/api/v2/orgs/1/webhooks/2/",
  "remote_url": "https://example.com/contacts/v2/",
  "token": "a3f7f07de894cd3c2f7f50248ccbd4",
  "created_at": "2018-03-30T00:00:16.159321Z",
  "updated_at": "2018-03-30T00:00:16.159321Z",
  "entity": "contact",
  "suspended_at": null
}

Webhook

GET

Retrieve details of a specific webhook.

GET /orgs/{org_pk}/webhooks/{webhook_pk}/

Example request:

curl -iL --request GET "https:/www.readycloud.com/api/v2/orgs/1/webhooks/1/?bearer_token=4ef5b29b1f4f35c383bebfccf4bf4d01"

Response 200 (application/json):

{
  "url": "/api/v2/orgs/1/webhooks/1/",
  "remote_url": "https://example.com/catch-rc-webhook/contacts/",
  "token": "a3f7f07de894cd3c2f7f50248ccbd4",
  "created_at": "2018-03-30T08:18:48Z",
  "updated_at": "2018-03-30T08:18:48Z",
  "entity": "contact",
  "suspended_at": null
}

DELETE

Delete a specific webhook.

DELETE /orgs/{org_pk}/webhooks/{webhook_pk}/

Response 204 (application/json)

Webhook Payload

Most order-related webhook types will send the same payload as described in the example below. Webhooks with custom payloads will be documented separately. This is the curl representation of the webhook being sent to the remote orders webhook URL https://example.com/orders/v2/ by ReadyCloud (note the appended object_pk_encoded):

curl -iL --request PUT -H "Auth: <webhook_token>" -H "Content-Type: application/json" --upload-file data.json "https://example.com/orders/v2/<object_pk_encoded>"

data.json:

{
    "billing": {
        "bill_to": null,
        "shipping": null,
        "status": null,
        "subtotal": null,
        "tax": null,
        "total": null
    },
    "boxes": [
        {
            "items": [],
            "url": "/api/v2/orgs/1/orders/4/boxes/5/"
        }
    ],
    "created_at": "2015-08-13T09:33:07Z",
    "custom_fields": {
        "additional_xml": {
            "type": "application/xml",
            "value": "<order>112233</order>"
        },
        "Bank deposit": {
            "value": "Can not check"
        },
        "Custom icon": {
            "type": "image/png",
            "value": "aGVsbG8sIHRoaXMgaXMgY3VzdG9tIGZpZWxk==",
            "encoding": "base64"
        }
    },
    "customer_number": null,
    "message": null,
    "nested_updated_at": "2015-08-13T09:33:07Z",
    "notes": [],
    "order_number": null,
    "ordered_at": "2014-12-17T15:34:11Z",
    "po_number": null,
    "primary_id": "127283",
    "printed_at": null,
    "relations": [],
    "shipping": {
        "ship_cost": null,
        "ship_from": {
            "address_1": "Belmont Street 45",
            "address_2": "Suite 56",
            "city": "New York",
            "company": "Toys R U",
            "country": "United States",
            "created_at": "2015-08-13T09:33:07Z",
            "email": "[email protected]",
            "first_name": "Shipping",
            "last_name": "Department",
            "phone": "6785851113",
            "post_code": "10019",
            "region": "NY",
            "residential": null,
            "updated_at": "2015-08-13T09:33:07Z",
            "validated": false
        },
        "ship_to": {
            "address_1": "900 Lincoln Dr",
            "address_2": "Apt 4",
            "city": "Scottsvale",
            "company": null,
            "country": "United States",
            "created_at": "2015-08-13T09:33:07Z",
            "email": "[email protected]",
            "first_name": "Nicholas",
            "last_name": "Testla",
            "phone": "6785851113",
            "post_code": "85257",
            "region": "AZ",
            "residential": null,
            "updated_at": "2015-08-13T09:33:07Z",
            "validated": false
        },
        "ship_agent": "ReadyShipper 10.0.1",
        "ship_type": null,
        "ship_via": null,
        "shipped_at": null,
        "status": null,
        "to_ship_at": null,
        "warehouse": null
    },
    "source": {
        "account": null,
        "channel": null,
        "id": null,
        "name": null,
        "retrieved_at": "2015-08-13T09:33:07Z",
        "updated_at": "2015-08-13T09:33:07Z"
    },
    "tags": ["new", "processed"],
    "terms": null,
    "unique_id": "00002yeYogO~zaetH-RlAqLY",
    "updated_at": "2015-08-13T09:33:07Z",
    "url": "/api/v2/orgs/1/orders/4/"
}

Note that if the webhook remote url fail to return status code 200 more than 3 times during a 6 hour timeframe it will be suspended.

This is the curl representation of the webhook being sent to the remote acceptance-scan webhook URL by ReadyCloud:

curl -iL --request PUT -H "Auth: <webhook_token>" -H "Content-Type: application/json" --upload-file data.json "https://example.com/acceptance-scan/v2/<box_pk_encoded>"

data.json:

{
  "url": "/api/v2/orgs/DP/orders/PK/",
  "box_url": "/api/v2/orgs/DP/orders/PK/boxes/8F/",
  "ship_cost": "2.34 USD",
  "tax": "7.65 USD",
  "packing_cost": "4.56 USD",
  "acceptance_scan_at": "2025-02-22T22:22:22Z"
}