Heseya documentation

Webhooks

Basic

This is functionality that is responsible for communicating with other applications or services. Webhooks are triggered for specific actions on the store side, for example, you can configure a webhook to trigger when a new order is created, after which detailed order information will be sent to the external application.

Webhook can be created by any user who has a webhooks.add permission, but specific webhooks may require additional permissions.

Sending process

Every send webhook follows this pattern:

  • After trigger specific event is created suitable query and added to queue
  • Executing each webhook from queue
  • Time out is set for 4s.
  • To let us know about successful delivery data we have to receive one of 2** HTTP code.
  • If we receive other code we will retry request but max 3 times.
  • Failed webhooks are logged in, and can be viewed in admin dashboard.

Signature

Optionally, the API can send a hashed payload that can be used to verify the authenticity of the request. To enable this feature, simply specify secret in the webhooks settings. The hash is generated using the HMAC method with the sha256 algorithm and will be sent in the Signature header. To verify the signature you must hash the payload with the sha256 algorithm. and compare your hash with the one received in the request header.

Secure webhooks

Some of our webhooks have fully encrypted payloads for security reasons - they can be found here.

This feature must be enabled by store administrator. Key is hidden in API files. Additionally, this requires SSL and Signature webhook.

Decoding payload

To do that, you have to get payload string and provide that to base64 decode function and then trim from beginning to length of WEBHOOK_CIPHER - keep that fragment it's important for next step - that will be your Initialization Vector. With these strings trimmed strings put them to OpenSSL decode functionopen in new window with information about:

  • Second part of trimmed string as data
  • WEBHOOK_CIPHER as cipher_algo
  • WEBHOOK_KEY as passphrase
  • OPENSSL_RAW_DATA as options
  • First part of trimmed string as iv

Structure of webhook

Webhooks

{
   "event": "string",
   "data_type": "string",
   "triggered_at": "DateTime", // ISO 8601
   "issuer_type": "string", // enum - app | user
   "issuer": { // when issuer is user
      "id": "UUID",
      "email": "string",
      "name": "string",
      "avatar": "string",
   },
   "issuer": { // when issuer is app
      "id": "UUID",
      "url": "string",
      "microfrontend_url": "string",
      "name": "string",
      "slug": "string",
      "version": "string",
      "description": "string",
      "icon": "string",
      "author": "string",
   },
   "api_url": "string", // Store api URL
   "data": {},
}

Available events

List of all events

* - It means permission is required when webhook has set with_hidden to true

EventRequirement permissionPayloadEncryption
OrderCreated
OrderUpdated
OrderUpdatedStatus		orders.show_details
orders.show
WebHookEvent<Order> & { data_type: 'Order' }
no
OrderRequestedShippingorders.show_details
orders.show
packages.show
type ShippingRequest = {order: Order, package: Package}

WebHookEvent<ShippingRequest> & { data_type: 'ShippingRequest' }
no
ProductCreated
ProductUpdated
ProductDeleted		products.show
products.show_details
products.show_hidden*
WebHookEvent<Product> & { data_type: 'Product' }
no
ItemCreated
ItemUpdated
ItemUpdatedQuantity
ItemDeleted		items.show
items.show_details
WebHookEvent<Item> & { data_type: 'Item' }
no
PageCreated
PageUpdated
PageDeleted		pages.show
pages.show_details
pages.show_hidden*
WebHookEvent<Page> & { data_type: 'Page' }
no
ProductSetCreated
ProductSetUpdated
ProductSetDeleted		product_sets.show
product_sets.show_details
product_sets.show_hidden*
WebHookEvent<ProductSet> & { data_type: 'ProductSet' }
no
UserCreated
UserUpdated
UserDeleted		users.show
users.show_details
WebHookEvent<User> & { data_type: 'User' }
no
DiscountCreated
DiscountUpdated
DiscountDeleted		discounts.show
discounts.show_details
WebHookEvent<Discount> & { data_type: 'Discount' }
no
LanguageCreated
LanguageUpdated
LanguageDeleted		languages.show_hidden*
WebHookEvent<Language> & { data_type: 'Language' }
no
TfaInit
TfaSecurityCode		webhooks.tfa
type TfaCode = { security_code: string, user: User }

WebHookEvent<TfaCode> & { data_type: 'TfaCode' }
yes
TfaRecoveryCodesChangedwebhooks.tfa
WebHookEvent<User> & { data_type: 'User' }
yes
PasswordResetwebhooks.password
type PasswordRecovery = { recovery_url: string, user: User, redirect_url: string }

WebHookEvent<PasswordRecovery > & { data_type: 'PasswordRecovery' }
yes
AddOrderDocument
RemoveOrderDocument		orders.show_details
type OrderDocumentEvent = { order: Order, document: OrderDocument }

WebHookEvent<OrderDocumentEvent> & { data_type: 'OrderDocument' }
no
SendOrderDocumentorders.show_details
type SendOrderDocument = { order: Order, documents: OrderDocument[] }

WebHookEvent<SendOrderDocument> & { data_type: 'SendOrderDocument' }
no
NewLocalizationLoginAttemptusers.show_details
type LocalizedLoginAttempt = { user_agent: string, ip: string, user: User, date: string }

WebHookEvent<LocalizedLoginAttempt> & { data_type: 'LocalizedLoginAttempt' }
yes
SuccessfullLoginAttemptusers.show_details
WebHookEvent<LocalizedLoginAttempt> & { data_type: 'LocalizedLoginAttempt' }
yes
FailedLoginAttemptusers.show_details
WebHookEvent<LocalizedLoginAttempt> & { data_type: 'LocalizedLoginAttempt' }
yes