Webhook Subscription Guide

List webhook subscriptions

To list webhooks subscriptions associated with your account, you can do a GET request to the following endpoint:

https://api.safsira.com/v1/core/webhooks/

Here is a list of webhook events you can subscribe to:

shipping_order.scheduled
shipping_order.changed
order.created
order.changed
custom_product.created
custom_product.changed

Subscribing to webhook

In order to subscribe to a webhook, you must send a POST request to the API to the following endpoint:

POST https://api.safsira.com/v1/core/webhooks/

Include the following payload:

    {
        "event": "event_type",
        "target": "url_to_send_webhook"
    }

If the subscription is successful, you will get a response like this:

    {
        "id": 7,
        "event": "event_type",
        "target": "url_to_send_webhook",
        "is_active": true,
        "account": "account_id"
    }

Unsubscribing from webhook

You can unsubscribe from the webhook at any time. Simply send a DELETE request on the API to the following endpoint:

DELETE https://api.safsira.com/v1/core/webhooks/:id/

If unsubscribing is successful, you will get an 204 http response.

Receiving a webhook

When a given webhook is triggered, you will receive a POST request on the endpoint you defined when you originally subscribed to that webhook. This request will have a payload containing information about the event that was triggered.

The payload will have the following structure:

{
    "hook": {
        "id": 7,
        "event": "event_type",
        "target": "url_to_send_webhook"
    },
    "data": {
        //...
    }
}

The hook key contains the metadata related to the webhook itself, while the data key contains the information related to the event that was triggered.

ℹ️

We always recommend you test your webhooks before pushing to production. Here are some tips:

Localhost can't be used as a webhook url
Use ngrok (opens in a new tab) to expose your local server to the internet
Use beeceptor (opens in a new tab) for testing

ℹ️

The data content of the following examples is just mock data and its structure can change at any time. We will update this documentation as soon as possible.

Shipping Order updated webhook (Shipment)

This webhook will trigger every time a shipping order is created/updated on your account (for example, when Tracking Number, Status, and any other relevant information changes). When a shipping_order.changed webhook is triggered, you will receive a POST request on the endpoint you defined when you subscribed to the webhook. This request will have a payload containing information about the shipping order that was created/updated:

Shipping Order Changed Event

Event type: shipping_order.changed

{
    "hook": {
        "id": 7,
        "event": "shipping_order.changed",
        "target": "url_to_send_webhook"
    },
    "data": {
        "id": 52671,
        "status": {
            "id": 1,
            "name": "Created"
        },
        "payment_status": {
            "id": "pending_payment",
            "name": "Pending payment"
        },
        "first_name": "John",
        "last_name": "Doe",
        "email": "john.doe@apple.com",
        "phone": "+5561992520669",
        "company": null,
        "address": {
            "line_1": "6289 Williams Fork",
            "line_2": null,
            "city": "Ashleyland",
            "state": "NJ",
            "postal_code": "31857",
            "country": "US",
            "is_po_box": false,
            "is_valid": true,
            "is_business_address": false
        },
        "shipping_date": "2023-07-10",
        "order": 26404,
        "shipping": {
            "currency": "USD",
            "amount": 12744,
            "display": "127.44"
        },
        "rate_id": null,
        "shipment_id": null,
        "shipping_method": {
            "id": "standard",
            "name": "Standard"
        },
        "recipient": {
            "id": 3049,
            "first_name": "Lisa",
            "last_name": "Franklin",
            "email": "lisa.franklin@apple.com",
            "phone": "+543434434",
            "company": null,
            "shipping_address": {
                "line_1": "6289 Williams Fork",
                "line_2": null,
                "city": "Ashleyland",
                "state": "NJ",
                "postal_code": "31857",
                "country": "US",
                "is_po_box": false,
                "is_valid": true,
                "is_business_address": false
            },
            "tags": [],
            "external_id": null,
            "source": {
                "id": 1,
                "name": "Manual"
            },
            "source_id": null
        },
        "payment_information": null,
        "invoice": 25348,
        "tracking_number": null,
        "tracking_url": null,
        "line_items": [
            {
                "id": 263,
                "part": {
                    "id": 22830,
                    "product_name": "Product PC90H",
                    "code": "SC-208-3950-3",
                    "image": "an_image_url.png",
                    "blank_image": "a_blank_image_url.png",
                    "variant": {
                        "size": {
                            "name": "L"
                        },
                        "color": {
                            "hex": "F9A122",
                            "name": "Gold"
                        }
                    },
                    "part_type": {
                        "id": 2,
                        "name": "Custom Part"
                    },
                    "items": [],
                    "imprint_area": null,
                    "design_status": {
                        "id": 4,
                        "name": "Approved"
                    },
                    "mockup_pdf_url": null
                },
                "quantity": 1
            },
            {
                "id": 264,
                "part": {
                    "id": 22818,
                    "product_name": "Product NL3900",
                    "code": "SC-208-3943-3",
                    "image": "an_image_url.png",
                    "blank_image": "a_blank_image_url.png",
                    "variant": {
                        "size": {
                            "name": "L"
                        },
                        "color": {
                            "hex": "1D242F",
                            "name": "Midnight Navy"
                        }
                    },
                    "part_type": {
                        "id": 2,
                        "name": "Custom Part"
                    },
                    "items": [],
                    "imprint_area": null,
                    "design_status": {
                        "id": 4,
                        "name": "Approved"
                    },
                    "mockup_pdf_url": null
                },
                "quantity": 1
            }
        ]
    }
}

Order updated webhook (Order)

This webhook will trigger every time an order is created/updated on your account (for example, when Status, Payment status, and any other relevant information changes). When an order.changed webhook is triggered, you will receive a POST request on the endpoint you defined when you subscribed to the webhook. This request will have a payload containing information about the order that was created/updated:

Order Changed Event

Event type: order.changed

{
    "hook": {
        "id": 8,
        "event": "order.changed",
        "target": "url_to_send_webhook"
    },
    "data": {
        "id": 26484,
        "status": {
            "id": 2,
            "name": "In Production"
        },
        "payment_status": {
            "id": "paid",
            "name": "Paid"
        },
        "created_at": "2023-08-17T16:45:17Z",
        "created_by": "john.doe@safsira.com",
        "modified_on": "2023-09-06T13:42:10.842050Z",
        "modified_by": null,
        "subtotal": {
            "currency": "USD",
            "amount": 1630,
            "display": "16.30"
        },
        "shipping": {
            "currency": "USD",
            "amount": 0,
            "display": "0.00"
        },
        "storage": {
            "currency": "USD",
            "amount": 400,
            "display": "4.00"
        },
        "tax": {
            "currency": "USD",
            "amount": 0,
            "display": "0.00"
        },
        "total": {
            "currency": "USD",
            "amount": 2030,
            "display": "20.30"
        },
        "line_items": [
            {
                "id": 495,
                "part": {
                    "id": 111926,
                    "product_name": "8th I think",
                    "product_id": 5819,
                    "code": "SC-231-5819-1",
                    "image": "an_image_url.png",
                    "blank_image": "a_blank_image_url.png",
                    "variant": {
                        "size": {
                            "name": "XS"
                        },
                        "color": {
                            "hex": "00A2C4",
                            "name": "Aqua"
                        }
                    },
                    "part_type": {
                        "id": 2,
                        "name": "Custom Part"
                    },
                    "product_weight": "0.2500",
                    "product_weight_unit": {
                        "id": "lb",
                        "name": "Pound"
                    },
                    "storage_category": {
                        "id": "MEDIUM",
                        "name": "Medium"
                    },
                    "imprint_area": null,
                    "product_production_time": 6,
                    "design_status": {
                        "id": 4,
                        "name": "Approved"
                    },
                    "mockup_pdf_url": null
                },
                "quantity": 1,
                "price": {
                    "currency": "USD",
                    "amount": 1630,
                    "display": "16.30"
                },
                "subtotal": {
                    "currency": "USD",
                    "amount": 1630,
                    "display": "16.30"
                },
                "status": {
                    "id": 1,
                    "name": "Pending"
                },
                "pack_items": []
            }
        ],
        "payment_information": null,
        "type": {
            "id": 2,
            "name": "Submitted"
        },
        "on_demand": false,
        "billing_address": {
            "line_1": "Some Address",
            "line_2": "",
            "city": "Hialeah",
            "state": "FL",
            "postal_code": "33013",
            "country": "US",
            "is_po_box": false,
            "is_valid": true,
            "is_business_address": false
        },
        "shipping_orders": [
            //... Shipments Associated with this order
        ]
    }
}

Custom Product created/updated webhook (Custom Product)

This webhook will trigger every time a Custom Product is created/updated on your account. When a webhook is triggered, you will receive a POST request on the endpoint you defined when you subscribed to the webhook. This request will have a payload containing information about the Custom Product that was created/updated. The Custom Product payload is similar to the payload used when retrieving a Custom Product.

ℹ️

The Custom Product creation process has several steps. The Custom Product payload will be updated as the process advances. Keep in mind that when you receive a custom_product.created webhook, the Custom Product may not be in its final state.

Custom Product Created Event

Event type: custom_product.created

{
    "hook": {
        "id": 8,
        "event": "custom_product.created",
        "target": "url_to_send_webhook"
    },
    "data": {
        "id": 6200,
        "name": "Moleskine Notebook",
        "description": "A reliable travel companion perfect for notes, sketches and thoughts. 3.5\" x 5.5\" bound hard cover notebook with rounded corners, bookmark and elastic strap closure. Expandable inner pocket. 192 acid-free, ruled pages and timeless Moleskine® quality. Features paper made of material from well-managed, FSC™-certified forests and other controlled sources.",
        "brand": "Moleskine",
        "prices": {
            "currency": "USD",
            "price": {
                "amount": 5000,
                "display": "50.00"
            }
        },
        "category": {
            "id": 10,
            "name": "Notebooks & Journals"
        },
        "categories": [
            {
                "id": 10,
                "name": "Notebooks & Journals"
            }
        ],
        "type": {
            "id": 2,
            "name": "Custom Product"
        },
        "slug": "moleskine-notebook-6200",
        "image": "an_image_url.png",
        "minimum": 1,
        "production_time": 7,
        "sellable": true,
        "tags": [],
        "rating": null,
        "default_part": {
            "id": 114182,
            "blank_image": "an_image_url.png",
            "image": "an_image_url.png",
            "variant": {
                "color": {
                    "hex": "3E4144",
                    "name": "Black"
                }
            },
            "imprint_area": null,
            "supplier_inventories": [
                {
                    "id": 90290,
                    "quantity": 0,
                    "is_available": true,
                    "is_pod": false
                }
            ]
        },
        "storage_category": {
            "id": "MEDIUM",
            "name": "Medium"
        },
        "weight": "0.3250",
        "weight_unit": {
            "id": "lb",
            "name": "Pound"
        },
        "is_pod": false,
        "design_status": {
            "id": 4,
            "name": "Approved"
        },
        "available_attributes": {
            "colors": [
                {
                    "hex": "3E4144",
                    "name": "Black"
                }
            ]
        },
        "unavailable_variants": [],
        "can_be_container": false,
        "can_be_filler": false,
        "unavailable_inventory_parts": [],
        "decorations": [
            {
                "mockup_image": "an_image_url.png",
                "notes": null,
                "location_decoration": {
                    "id": 33245,
                    "supplier": 34,
                    "active": true,
                    "location": {
                        "id": 1397,
                        "name": "Full Front"
                    },
                    "imprint_method": {
                        "id": 4,
                        "name": "Screen Print"
                    },
                    "supplier_imprint_method": "Print",
                    "max_imprint_colors": 8,
                    "default": true,
                    "default_number_colors": 1
                }
            }
        ],
        "blank_image": null,
        "design_lab_ready": false,
        "max_sample_quantity": 0,
        "sample_price": 0,
        "selected_mockup": {
            "id": 1508,
            "product": 6200,
            "type": {
                "id": 2,
                "name": "Custom Product"
            },
            "image": "an_image_url.png",
            "needs_design": true,
            "design_status": {
                "id": 4,
                "name": "Approved"
            },
            "mockup_location_details": [
                {
                    "id": 1687,
                    "image": "an_image_url.png",
                    "artwork": null,
                    "dimensions": null,
                    "location_decoration": {
                        "id": 33245,
                        "supplier": 34,
                        "active": true,
                        "location": {
                            "id": 1397,
                            "name": "Full Front"
                        },
                        "imprint_method": {
                            "id": 4,
                            "name": "Screen Print"
                        },
                        "supplier_imprint_method": "Print",
                        "max_imprint_colors": 8,
                        "default": true,
                        "default_number_colors": 1
                    },
                    "design_lab_info": {
                        ...
                    }
                }
            ],
            "children": [],
            "mockup_pdf_url": null
        },
        "number_of_variants": 1,
        "requires_design": false
    }
}

Developer Apps Embeddable Design Lab