Yofi API Webhooks

Sending data to Yofi

post

The Yofi Webhook API allows our partners to send real-time data about orders, customers, returns, and refunds directly to Yofi.
This data enables advanced analysis and provides valuable insights into your business.
The webhook uses a secure, signature-based authentication mechanism to ensure data integrity and origin verification.

Partner can request on this API endpoint to send data to Yofi, including events of order/fulfillment/claim/return.

The request body contains the raw object of an order/fulfillment/claim/return, varying based on the x-event-type header.

Check the following examples to see request body for each data type. For example,
for order event type, payload should be an raw order object,
while for fulfillment event, payload should be an raw fulfillment object.

Notes:

The payload data should be a complete data object with mandatory fields
- for example the created_at field is required in customer nested object for order event.
Historical data older than 30days will be skipped for processing.
For order events, orders/create event is skipped for processing by Yofi backend, as it's duplicate event with orders/paid

Sample python code to generate `X-Signature-SHA256`


import hashlib
import hmac
import base64
payload_body = """{order_fields:"...."}"""
partner_secret = "secret_key_to_provided_by_yofi"
digest = hmac.new(partner_secret.encode('utf-8'),
                  msg=payload_body.encode('utf-8'),
                  digestmod=hashlib.sha256).digest()
sign_sha256 = base64.b64encode(digest).decode('utf-8')
print(sign_sha256)

Header parameters

X-Signature-SHA256stringRequired

Base64 encoded HMAC SHA256 signature of the request payload, used for verifying the request authenticity. Use the secret key(provided with Yofi) to generate.

Example: QMe+tAtZLBB6S/7Fyil6UpBfIiHb7Kem8kBily20i9Q=

x-partner-idstringRequired

Identifier for the partner receiving the webhook.

Example: demo

x-merchant-idstringRequired

Identifier for the specific merchant of the event.

Example: yofi_partner_demo.myshopify.com

x-event-typestringRequired

Type of the event being sent, request payload body should be the data object according to this type, like order, fulfillment, claim or return.

For order

orders/paid
orders/cancelled
orders/updated
orders/edited
orders/create
orders/delete
orders/fulfilled
orders/partially_fulfilled

For customers

customer/create
customer/update

For events

event/create

For fulfillment:

fulfillments/create
fulfillments/update

For claims

claims/create
claims/update

For returns

returns/create
returns/update

Example: xxx_input_your_event_type_here

Body

idintegerRequired

The source id of the resource, based on the data of source platform like Shopify

created_atstringRequired

The source created_at of the source resource object, based on data of source platform like Shopify.

partner_resource_idstringOptional

Optional: the resource id in partner database

partner_resource_platformstringOptional

Optional: the platform that the resource come from, like shopify, woocommerce, magento, bigcommerce, api

...other_field_of_the_data_object...stringOptional

Other fields of order/fulfillment/claim/return, according to event type, refer to shopify api docs

Responses

200

Successfully Received!

text/plain

400

Request invalid

text/plain

401

Payload incorrect

text/plain

403

Data conflict

text/plain

503

Server Error

text/plain

post

/webhook

POST /webhook HTTP/1.1
Host: api-partner.botnot.io
X-Signature-SHA256: QMe+tAtZLBB6S/7Fyil6UpBfIiHb7Kem8kBily20i9Q=
x-partner-id: demo
x-merchant-id: yofi_partner_demo.myshopify.com
x-event-type: xxx_input_your_event_type_here
Content-Type: application/json
Accept: */*
Content-Length: 9038

{
  "partner_resource_id": "partner_resouce_uid_xxxx",
  "partner_resource_platform": "shopify",
  "metadata": {
    "optional_field1_from_partner": "any_value",
    "optional_field2_from_partner": "any_value",
    "optional_field3_from_partner": "..."
  },
  "id": 820982911946154500,
  "admin_graphql_api_id": "gid://shopify/Order/820982911946154508",
  "app_id": null,
  "browser_ip": null,
  "buyer_accepts_marketing": true,
  "cancel_reason": "customer",
  "cancelled_at": "2021-12-31T19:00:00-05:00",
  "cart_token": null,
  "checkout_id": null,
  "checkout_token": null,
  "client_details": null,
  "closed_at": null,
  "confirmation_number": null,
  "confirmed": false,
  "contact_email": "[email protected]",
  "created_at": "2021-12-31T19:00:00-05:00",
  "currency": "USD",
  "current_shipping_price_set": {
    "shop_money": {
      "amount": "0.00",
      "currency_code": "USD"
    },
    "presentment_money": {
      "amount": "0.00",
      "currency_code": "USD"
    }
  },
  "current_subtotal_price": "369.97",
  "current_subtotal_price_set": {
    "shop_money": {
      "amount": "369.97",
      "currency_code": "USD"
    },
    "presentment_money": {
      "amount": "369.97",
      "currency_code": "USD"
    }
  },
  "current_total_additional_fees_set": null,
  "current_total_discounts": "0.00",
  "current_total_discounts_set": {
    "shop_money": {
      "amount": "0.00",
      "currency_code": "USD"
    },
    "presentment_money": {
      "amount": "0.00",
      "currency_code": "USD"
    }
  },
  "current_total_duties_set": null,
  "current_total_price": "369.97",
  "current_total_price_set": {
    "shop_money": {
      "amount": "369.97",
      "currency_code": "USD"
    },
    "presentment_money": {
      "amount": "369.97",
      "currency_code": "USD"
    }
  },
  "current_total_tax": "0.00",
  "current_total_tax_set": {
    "shop_money": {
      "amount": "0.00",
      "currency_code": "USD"
    },
    "presentment_money": {
      "amount": "0.00",
      "currency_code": "USD"
    }
  },
  "customer_locale": "en",
  "device_id": null,
  "discount_codes": [],
  "duties_included": false,
  "email": "[email protected]",
  "estimated_taxes": false,
  "financial_status": "voided",
  "fulfillment_status": null,
  "landing_site": null,
  "landing_site_ref": null,
  "location_id": null,
  "merchant_business_entity_id": "MTU0ODM4MDAwOQ",
  "merchant_of_record_app_id": null,
  "name": "#9999",
  "note": null,
  "note_attributes": [],
  "number": 234,
  "order_number": 1234,
  "order_status_url": "https://jsmith.myshopify.com/548380009/orders/123456abcd/authenticate?key=abcdefg",
  "original_total_additional_fees_set": null,
  "original_total_duties_set": null,
  "payment_gateway_names": [
    "visa",
    "bogus"
  ],
  "phone": null,
  "po_number": null,
  "presentment_currency": "USD",
  "processed_at": "2021-12-31T19:00:00-05:00",
  "reference": null,
  "referring_site": null,
  "source_identifier": null,
  "source_name": "web",
  "source_url": null,
  "subtotal_price": "359.97",
  "subtotal_price_set": {
    "shop_money": {
      "amount": "359.97",
      "currency_code": "USD"
    },
    "presentment_money": {
      "amount": "359.97",
      "currency_code": "USD"
    }
  },
  "tags": "tag1, tag2",
  "tax_exempt": false,
  "tax_lines": [],
  "taxes_included": false,
  "test": true,
  "token": "123456abcd",
  "total_cash_rounding_payment_adjustment_set": {
    "shop_money": {
      "amount": "0.00",
      "currency_code": "USD"
    },
    "presentment_money": {
      "amount": "0.00",
      "currency_code": "USD"
    }
  },
  "total_cash_rounding_refund_adjustment_set": {
    "shop_money": {
      "amount": "0.00",
      "currency_code": "USD"
    },
    "presentment_money": {
      "amount": "0.00",
      "currency_code": "USD"
    }
  },
  "total_discounts": "20.00",
  "total_discounts_set": {
    "shop_money": {
      "amount": "20.00",
      "currency_code": "USD"
    },
    "presentment_money": {
      "amount": "20.00",
      "currency_code": "USD"
    }
  },
  "total_line_items_price": "369.97",
  "total_line_items_price_set": {
    "shop_money": {
      "amount": "369.97",
      "currency_code": "USD"
    },
    "presentment_money": {
      "amount": "369.97",
      "currency_code": "USD"
    }
  },
  "total_outstanding": "369.97",
  "total_price": "359.97",
  "total_price_set": {
    "shop_money": {
      "amount": "359.97",
      "currency_code": "USD"
    },
    "presentment_money": {
      "amount": "359.97",
      "currency_code": "USD"
    }
  },
  "total_shipping_price_set": {
    "shop_money": {
      "amount": "10.00",
      "currency_code": "USD"
    },
    "presentment_money": {
      "amount": "10.00",
      "currency_code": "USD"
    }
  },
  "total_tax": "0.00",
  "total_tax_set": {
    "shop_money": {
      "amount": "0.00",
      "currency_code": "USD"
    },
    "presentment_money": {
      "amount": "0.00",
      "currency_code": "USD"
    }
  },
  "total_tip_received": "0.00",
  "total_weight": 0,
  "updated_at": "2021-12-31T19:00:00-05:00",
  "user_id": null,
  "billing_address": {
    "first_name": "Steve",
    "address1": "123 Shipping Street",
    "phone": "555-555-SHIP",
    "city": "Shippington",
    "zip": "40003",
    "province": "Kentucky",
    "country": "United States",
    "last_name": "Shipper",
    "address2": null,
    "company": "Shipping Company",
    "latitude": null,
    "longitude": null,
    "name": "Steve Shipper",
    "country_code": "US",
    "province_code": "KY"
  },
  "customer": {
    "id": 115310627314723950,
    "email": "[email protected]",
    "created_at": null,
    "updated_at": null,
    "first_name": "John",
    "last_name": "Smith",
    "full_name": "John Smith",
    "state": "disabled",
    "note": null,
    "verified_email": true,
    "multipass_identifier": null,
    "tax_exempt": false,
    "phone": null,
    "currency": "USD",
    "tax_exemptions": [],
    "admin_graphql_api_id": "gid://shopify/Customer/115310627314723954",
    "default_address": {
      "id": 715243470612851200,
      "customer_id": 115310627314723950,
      "first_name": null,
      "last_name": null,
      "company": null,
      "address1": "123 Elm St.",
      "address2": null,
      "city": "Ottawa",
      "province": "Ontario",
      "country": "Canada",
      "zip": "K2H7A8",
      "phone": "123-123-1234",
      "name": "",
      "province_code": "ON",
      "country_code": "CA",
      "country_name": "Canada",
      "default": true
    }
  },
  "discount_applications": [],
  "fulfillments": [],
  "line_items": [
    {
      "id": 487817672276298560,
      "admin_graphql_api_id": "gid://shopify/LineItem/487817672276298554",
      "attributed_staffs": [
        {
          "id": "gid://shopify/StaffMember/902541635",
          "quantity": 1
        }
      ],
      "current_quantity": 1,
      "fulfillable_quantity": 1,
      "fulfillment_service": "manual",
      "fulfillment_status": null,
      "gift_card": false,
      "grams": 100,
      "name": "Aviator sunglasses",
      "price": "89.99",
      "price_set": {
        "shop_money": {
          "amount": "89.99",
          "currency_code": "USD"
        },
        "presentment_money": {
          "amount": "89.99",
          "currency_code": "USD"
        }
      },
      "product_exists": true,
      "product_id": 788032119674292900,
      "properties": [],
      "quantity": 1,
      "requires_shipping": true,
      "sales_line_item_group_id": null,
      "sku": "SKU2006-001",
      "taxable": true,
      "title": "Aviator sunglasses",
      "total_discount": "0.00",
      "total_discount_set": {
        "shop_money": {
          "amount": "0.00",
          "currency_code": "USD"
        },
        "presentment_money": {
          "amount": "0.00",
          "currency_code": "USD"
        }
      },
      "variant_id": null,
      "variant_inventory_management": null,
      "variant_title": null,
      "vendor": null,
      "tax_lines": [],
      "duties": [],
      "discount_allocations": []
    },
    {
      "id": 976318377106520300,
      "admin_graphql_api_id": "gid://shopify/LineItem/976318377106520349",
      "attributed_staffs": [],
      "current_quantity": 1,
      "fulfillable_quantity": 1,
      "fulfillment_service": "manual",
      "fulfillment_status": null,
      "gift_card": false,
      "grams": 1000,
      "name": "Mid-century lounger",
      "price": "159.99",
      "price_set": {
        "shop_money": {
          "amount": "159.99",
          "currency_code": "USD"
        },
        "presentment_money": {
          "amount": "159.99",
          "currency_code": "USD"
        }
      },
      "product_exists": true,
      "product_id": 788032119674292900,
      "properties": [],
      "quantity": 1,
      "requires_shipping": true,
      "sales_line_item_group_id": 142831562,
      "sku": "SKU2006-020",
      "taxable": true,
      "title": "Mid-century lounger",
      "total_discount": "0.00",
      "total_discount_set": {
        "shop_money": {
          "amount": "0.00",
          "currency_code": "USD"
        },
        "presentment_money": {
          "amount": "0.00",
          "currency_code": "USD"
        }
      },
      "variant_id": null,
      "variant_inventory_management": null,
      "variant_title": null,
      "vendor": null,
      "tax_lines": [],
      "duties": [],
      "discount_allocations": []
    },
    {
      "id": 315789986012684400,
      "admin_graphql_api_id": "gid://shopify/LineItem/315789986012684393",
      "attributed_staffs": [],
      "current_quantity": 1,
      "fulfillable_quantity": 1,
      "fulfillment_service": "manual",
      "fulfillment_status": null,
      "gift_card": false,
      "grams": 500,
      "name": "Coffee table",
      "price": "119.99",
      "price_set": {
        "shop_money": {
          "amount": "119.99",
          "currency_code": "USD"
        },
        "presentment_money": {
          "amount": "119.99",
          "currency_code": "USD"
        }
      },
      "product_exists": true,
      "product_id": 788032119674292900,
      "properties": [],
      "quantity": 1,
      "requires_shipping": true,
      "sales_line_item_group_id": 142831562,
      "sku": "SKU2006-035",
      "taxable": true,
      "title": "Coffee table",
      "total_discount": "0.00",
      "total_discount_set": {
        "shop_money": {
          "amount": "0.00",
          "currency_code": "USD"
        },
        "presentment_money": {
          "amount": "0.00",
          "currency_code": "USD"
        }
      },
      "variant_id": null,
      "variant_inventory_management": null,
      "variant_title": null,
      "vendor": null,
      "tax_lines": [],
      "duties": [],
      "discount_allocations": []
    }
  ],
  "payment_terms": null,
  "refunds": [],
  "shipping_address": {
    "first_name": "Steve",
    "address1": "123 Shipping Street",
    "phone": "555-555-SHIP",
    "city": "Shippington",
    "zip": "40003",
    "province": "Kentucky",
    "country": "United States",
    "last_name": "Shipper",
    "address2": null,
    "company": "Shipping Company",
    "latitude": null,
    "longitude": null,
    "name": "Steve Shipper",
    "country_code": "US",
    "province_code": "KY"
  },
  "shipping_lines": [
    {
      "id": 271878346596884000,
      "carrier_identifier": null,
      "code": null,
      "current_discounted_price_set": {
        "shop_money": {
          "amount": "0.00",
          "currency_code": "USD"
        },
        "presentment_money": {
          "amount": "0.00",
          "currency_code": "USD"
        }
      },
      "discounted_price": "10.00",
      "discounted_price_set": {
        "shop_money": {
          "amount": "10.00",
          "currency_code": "USD"
        },
        "presentment_money": {
          "amount": "10.00",
          "currency_code": "USD"
        }
      },
      "is_removed": false,
      "phone": null,
      "price": "10.00",
      "price_set": {
        "shop_money": {
          "amount": "10.00",
          "currency_code": "USD"
        },
        "presentment_money": {
          "amount": "10.00",
          "currency_code": "USD"
        }
      },
      "requested_fulfillment_service_id": null,
      "source": "shopify",
      "title": "Generic Shipping",
      "tax_lines": [],
      "discount_allocations": []
    }
  ],
  "returns": []
}

Webhook event processed.

PreviousData Transfer NextCloud Storage Data Transfer

Last updated 1 month ago

Was this helpful?

Sending data to Yofi

Notes:

Sample python code to generate X-Signature-SHA256

Sample python code to generate `X-Signature-SHA256`