Webhooks

Wooxy can make an HTTP POST request to your URL when events occur with your messages (sent and delivered events are exceptions). If you would like Wooxy to POST event notifications, you need to provide a Callback URL in the the Control Panel.

The Wooxy POST request to your Callback URL will come from following IP address: 188.226.196.117. Please, add it to your Firewall whitelist.

Wooxy will keep the connection for 1.5 seconds. If the status code 200 is not received, the connection will be dropped and another attempt made after a short delay to deliver the webhooks.

If the webhook delivery fails, we will make 15 attempts to deliver the webhook before dropping it from the queue.

Number of attempts	Seconds between attempts
3	100
6	600
6	3600

Specific Message Callback Events

If you have provided webHookUri in your account, Wooxy will send a POST request to it with the status of the Email message.

Body Example

JSON

                {
    "datetime": 1234567890,
    "event": "read",
    "email": "user@example.com",
    "id": "5537ab2a08d241dc69326b19",
    "userId": "myUserId-1"
    "headers": {
        "X-Additional-Header": "additional-header-value"
    }
}

Parameters

Callback URL
datetime	The time when the event was generated in the system provided as Unix epoch seconds.
event	The type of the event.
	read	The email recipient opened the email and enabled image viewing.
	click	The email recipient clicked on a link in the email.
	hard	The ISP server returned hard-bounce for this message
	complaint	The email recipient clicked on a Spam button in his inbox.
	list-unsubscribe	The email recipient requested unsubscription from all emails in his inbox using “list-unsubscribe” technology.
	reject	The email address is in black list
email	The email address of the recipient
id	The message unique identification number in Wooxy system
userId	Contact’s unique userId from your platform enables management of the contact in the list based on it. IMPORTANT: The userId should be added beforehand to the contact list for a specific contact; otherwise, the value will be Null IMPORTANT: Event with 'reject' type will not have 'userId' in the webhook.
headers	Optional extra headers added to the message.

Contact Management Callback Events

If you have provided webHookUri in your account, Wooxy will send a POST request to it with information regarding changes of the contact status in the Contact List.

Body Example

JSON

                {
    "event": "subscribed",
    "email": "user@example.com",
    "datetime": 1483010763,
    "contactId": "60890ee5890ede9d2c70a077",
    "emailListId": "5537ab2a08d241dc69326b19",
    "phoneNumber": "+155555555",
    "userId": "myUserId-1"
}

Parameters

Callback URL
event	The type of the event.
	subscribed	The contact subscribed to Email channel in the specified contact list.
	unsubscribed	The contact unsubscribed from Email channel in the specified contact list.
	sms-subscribed	The contact subscribed to SMS channel in the specified contact list.
	sms-unsubscribed	The contact unsubscribed from SMS channel in the specified contact list.
	web-push-contact-desktop-subscribed	The contact subscribed to Desktop Web Push channel in the specified contact list.
	web-push-contact-desktop-unsubscribed	The contact unsubscribed from Desktop Web Pushail channel in the specified contact list.
	web-push-contact-mobile-subscribed	The contact subscribed to Mobile Web Push channel in the specified contact list.
	web-push-contact-mobile-unsubscribed	The contact unsubscribed from Mobile Web Push channel in the specified contact list.
	telegram-contact-channel-subscribed	The contact subscribed to Telegram channel in the specified contact list.
	telegram-contact-channel-unsubscribed	The contact unsubscribed from Telegram channel in the specified contact list.
email	The email address of the recipient
datetime	The time when the event was generated in the system provided as Unix epoch seconds.
contactId	The message unique identification number for the contact in Wooxy system
emailListId	The ID of the contact list to which the contact belongs. The contact list already should be created in your account on the Lists page: https://app.wooxy.com/email-list/
phoneNumber	Addressee phoneNumber.
userId	Contact’s unique userId from your platform enables management of the contact in the list based on it. IMPORTANT: The userId should be added beforehand to the contact list for a specific contact; otherwise, the value will be Null IMPORTANT: Event with 'reject' type will not have 'userId' in the webhook.
Variable for unsubscribe	This webhook will work only if unsubscribes are handled by Wooxy via variable {{unSubscribeUrl}}

Email Delivery Status

If you have provided webHookUri in your account, Wooxy will send a POST request to it with the status as soon as it is accepted by ISP.

The following are key operational details:

Any webhook batch that does not receive an HTTP 200 response will be retried for a total of 8 hours before the data is discarded.
Webhooks posting to your endpoint will timeout after 10 seconds. For best results, write webhook batches to disk and then process asynchronously to minimize data loss if you have a problem with your database.
One message delivery webhook can be included up to 100 messages. The number is optional and may include less messages.

Body Example

JSON

                {
  "event": "delivered",
  "messages": {
    "5537ab2a08d241dc69326b19": {
      "id": "5537ab2a08d241dc69326b19",
      "email": "user@example.com",
      "datetime": 1510676506,
      "userId": "myUserId-1"
      "info": {
        "type": "transaction"
      },
      "headers": {
          "X-Additional-Header": "additional-header-value"
      }
    },
    "5537ab2a08d241dc69326b20": {
      "id": "5537ab2a08d241dc69326b20",
      "email": "user-2@example.com",
      "datetime": 1510676506,
      "userId": "myUserId-2"
      "info": {
        "type": "campaign",
        "id": "59bbcc21f97239a65e546569",
      },
      "headers": {
          "X-Additional-Header": "additional-header-value"
      }
    },
    "5537ab2a08d241dc69326b21": {
      "id": "5537ab2a08d241dc69326b21",
      "email": "user-3@example.com",
      "datetime": 1510676506,
      "userId": "myUserId-3"
      "info": {
        "type": "automation",
        "id": "59bbcc21f97239a65e546570"
      }
     "headers": null
    }
  }
}

Parameters

Parameters
event	The type of the event.
	Delivered	The ISP server returned 250 (accepted & queued for delivery) for this message
messages	Message object where the key is the unique message id and value information on the specific message
	message_id	The message unique identification number in Wooxy system
		id	The message unique identification number in Wooxy system
		email	The email address of the recipient
		datetime	Unix timestamp (seconds from epoch)
		userId	Contact’s unique `userId` from your platform enables management of the contact in the list based on it. IMPORTANT: The userId should be added beforehand to the contact list for a specific contact; otherwise, the value will be Null IMPORTANT: Event with 'reject' type will not have 'userId' in the webhook.
		info	Object with additional information
			type	Message type
				transaction	Message was send via API as a transactional
				campaign	Message was send as a one time promo campaign from admin panel
				automation	Message was send from automation set up in admin panel
			id 'optional'	Available only for messages with campaign or automation types
				campaign_id	The promo campaign unique identification number in Wooxy system
				scenario_id	The automation unique identification number in Wooxy system
			title 'optional'	The specific campaign name typed in Wooxy during creation. IMPORTANT: Available only for messages with campaign type.
		headers	Optional extra headers added to the message.

SMS Delivery Status

If you have provided webHookUri in your account, Wooxy will send a POST request to it with the status of the SMS as soon as it is accepted by Mobile Operator.

Body Example

JSON

                {
   "datetime": 1234567890,
   "event": "sms_delivered",
   "phoneNumber": "+155555555",
   "userId": "myUserId-1",
   "email": "user@example.com",
   "id": "5537ab2a08d241dc69326b19"
}

Parameters

Callback URL
datetime	Request time in Unix_Timestamp format
event	The type of the event.
	sms_delivered	The SMS was successfully delivered to recipient.
phoneNumber	Addressee phoneNumber.
userId	Contact’s unique userId from your platform enables management of the contact in the list based on it. IMPORTANT: The userId should be added beforehand to the contact list for a specific contact; otherwise, the value will be Null IMPORTANT: Event with 'reject' type will not have 'userId' in the webhook.
email	The email address of the recipient
id	The SMS unique identification number in Wooxy system

Telegram Delivery Status

If you have provided webHookUri in your account, Wooxy will send a POST request to it with the status of the message as soon as it is accepted by Telegram.

Body Example

JSON

                {
  "datetime": 1234567890,
  "event": "telegram-delivered",
  "id": "5537ab2a08d241dc69326b19",
  "botId": "60891092890ede99356891u7",
  "contactId": "60890ee5890ede9d2c70a077",
  "emailListId": "60224b6a890ededbb63493yy",
  "phoneNumber": "+155555555",
  "userId": "myUserId-1",
  "email": "user@example.com"
}

Parameters

Callback URL
datetime	Request time in Unix_Timestamp format
event	The type of the event.
	telegram-delivered	The message was successfully delivered to the recipient.
	telegram-viewed	The recipient opened the message
	telegram-clicked	The email recipient clicked on a link in the message.
id	The Telegram message unique identification in the Wooxy system
botId	Unique Telegram botId that is already registered
contactId	The unique identification number for the contact in the Wooxy system
emailListId	The ID of the contact list to which the contact belongs. The contact list already should be created in your account on the Lists page: https://app.wooxy.com/email-list/
phoneNumber	Addressee phoneNumber.
userId	Contact’s unique userId from your platform enables management of the contact in the list based on it. IMPORTANT: The userId should be added beforehand to the contact list for a specific contact; otherwise, the value will be Null IMPORTANT: Event with 'reject' type will not have 'userId' in the webhook.
email	The email address of the recipient

WebPush Delivery Status

If you have provided webHookUri in your account, Wooxy will send a POST request to it with the status of the WebPush as soon as it is accepted by Browser.

Body Example

JSON

                {
  "datetime": 1234567890,
  "event": "web-push-delivered",
  "id": "5537ab2a08d241dc69326b19",
  "webSiteId": "60379473a813802d276922b1"
  "contactId": "60890ee5890ede9d2c70a02d",
  "emailListId": "60224b6a890ededbb63493ee",
  "phoneNumber": "+155555555",
  "userId": "myUserId-1",
  "email": "user@example.com"
}

Parameters

Callback URL
datetime	Request time in Unix_Timestamp format
event	The type of the event.
	webPush-delivered	The message was successfully delivered to the recipient.
	webPush-open	The recipient opened the message
	webPush-clicked	The email recipient clicked on a link in the message.
id	The webPush message unique identification in the Wooxy system
webSiteId	Unique Website Id that is already registered
contactId	The unique identification number for the contact in the Wooxy system
emailListId	The ID of the contact list to which the contact belongs. The contact list already should be created in your account on the Lists page: https://app.wooxy.com/email-list/
phoneNumber	Addressee phoneNumber.
userId	Contact’s unique userId from your platform enables management of the contact in the list based on it. IMPORTANT: The userId should be added beforehand to the contact list for a specific contact; otherwise, the value will be Null IMPORTANT: Event with 'reject' type will not have 'userId' in the webhook.
email	The email address of the recipient

Viber Delivery Status

If you have provided webHookUri in your account, Wooxy will send a POST request to it with the status of the message as soon as it is accepted by Viber.

Body Example

JSON

                {
  "datetime": 1234567890,
  "event": "viber-delivered",
  "id": "5537ab2a08d241dc69326b19",
  "contactId": "60890ee5890ede9d2c70a02d",
  "emailListId": "60224b6a890ededbb63493ee",
  "phoneNumber": "+155555555",
}

Parameters

Callback URL
datetime	Request time in Unix_Timestamp format
event	The type of the event.
	viber-delivered	The message was successfully delivered to the recipient.
	viber-viewed	The recipient opened the message
	viber-failed	The message delivery in Viber application failed
id	The Viber message unique identification in the Wooxy system
contactId	The unique identification number for the contact in the Wooxy system
emailListId	The ID of the contact list to which the contact belongs. The contact list already should be created in your account on the Lists page: https://app.wooxy.com/email-list/
phoneNumber	Addressee phoneNumber.

Subaccount Create Status Success

If you provide a value for the parameter webhookUri when sending the request to create a subaccount using the API method Subaccount Create, you will receive a request confirming the successful creation of your subaccount.

Important! This request is sent at the moment when the subaccount has been fully created.

Body Example

JSON

                {
  "event": "sub_account_creation_success",
  "subAccount": {
    "name": "SUBACCOUNT_NAME",
    "subscription": "month",
    "country": "SUBACCOUNT_COUNTRY_ISO_ALPHA_2",
    "timezone": "Europe/Tallinn",
    "id": "ACCOUNT_ID"
  },
  "owner": {
    "email": "SUBACCOUNT_EMAIL",
    "password": "******",
    "firstName": "SUBACCOUNT_FIRSTNAME",
    "lastName": "AUBACCOUNT_LASTNAME",
    "id": "USER_ID",
    "token": "SUBACCOUNT_API_KEY"
  }
}

Parameters

Callback URL
event	sub_account_creation_success	This status indicates that the subaccount has been successfully created.
subAccount	Object with the parameters of the created subaccount.
	name	Subaccount name.
	subscription	The plan selected for creating the subaccount. You can change it by contacting us at support@wooxy.com.
	country	The country of the subaccount.
	timezone	Account's timezone
	id	Account identifier
owner	Object with key parameters of your subaccount necessary for login, etc.
	email	Email that can be used to log in to the subaccount.
	password	Password that can be used to log in to the subaccount.
	firstName	Subaccount First Name
	lastName	Subaccount Last Name
	id	User identifier
	token	API key of your subaccount.

Subaccount Create Status Failed

Important! This request is sent at the moment when the subaccount has been fully created or the creation will fail.

Important! If the error occurred due to insufficient funds in the balance, you need to check the balance and only after the required amount is available, resend the request.

Body Example

JSON

                {
  "event": "sub_account_creation_error",
  "subAccount": {
    "name": "SUBACCOUNT_NAME",
    "subscription": "month",
    "country": "SUBACCOUNT_COUNTRY_ISO_ALPHA_2",
    "timezone": "Europe/Tallinn",
    "id": "ACCOUNT_ID"
  },
  "owner": {
    "email": "SUBACCOUNT_EMAIL",
    "password": "******",
    "firstName": "SUBACCOUNT_FIRSTNAME",
    "lastName": "AUBACCOUNT_LASTNAME",
    "id": "USER_ID",
    "token": "SUBACCOUNT_API_KEY"
  },
  "error": "transaction failed"
}

Parameters

Callback URL
event	sub_account_creation_error	This parameter indicates that an error occurred during the creation of the subaccount.
subAccount	Object with the parameters of the created subaccount.
	name	Subaccount name.
	subscription	The plan selected for creating the subaccount. You can change it by contacting us at support@wooxy.com.
	country	The country of the subaccount.
	timezone	Account's timezone
owner	Object with key parameters of your subaccount necessary for login, etc.
	email	Email that can be used to log in to the subaccount.
	password	Password that can be used to log in to the subaccount.
	firstName	Subaccount First Name
	lastName	Subaccount Last Name
error	Description of the error that occurred.

Domain Creation Status

When using the API method for Domain Creation, you can add the webhookUri parameter to receive a request with data once the domain creation and necessary record generation are complete.

Important! The request will arrive at the moment when the domain has been fully created and all records have been generated.

Body Example

JSON

                {
  "account": {
    "id": "ACCOUNT_ID",
    "name": "ACCOUNT_NAME"
  },
  "domain": {
    "id": "DOMAIN_ID",
    "name": "DOMAIN"
  },
  "event": "domain_dns_records_created"
}

Parameters

Callback URL
account	Object with account data in which the new domain has been added.
	id	Account identifier
	name	Account name
domain	Object with data about the created domain.
	id	Domain identifier
	name	Created domain
event	domain_dns_records_created	The event that indicates the DNS records for the domain have been successfully generated and the domain has been created.

Domain Remove Status

When using the API method for Domain Deletion, there is an option to specify the webhookUri parameter, to which a request with additional information about the deletion will be sent after the domain is deleted.

Important! The webhook will be sent only after the domain is fully deleted. This process may take some time as the domain may have many entities that require time to be removed.

Body Example

JSON

                {
  "account": {
    "id": "ACCOUNT_ID",
    "name": "ACCOUNT_NAME"
  },
  "domain": {
    "id": "DOMAIN_ID",
    "name": "DOMAIN"
  },
  "event": "domain_removed"
}

Parameters

Callback URL
account	Object with account data in which the new domain has been removed.
	id	Account identifier
	name	Account name
domain	Object with data about the removed domain.
	id	Domain identifier
	name	Removed domain
event	domain_removed	The event that indicates the DNS records for the domain have been successfully removed, and all entities associated with the domain have also been removed.

Need Help?

Our technical support team will be happy to help with your integration. They are at your disposal 24/7.

Just send us a line by following email address with the information where you have been stuck so we could help faster: support@wooxy.com.