Create Webhook

Call this endpoint as a POST request to register a webhook using the URL that you have provided in the body.

Endpoint

Method	URL
POST	https://api.everlytic.net/transactional/email/v1/webhooks

Request Body

{
  "event_types": [
    "string"
  ],
  "url": "string",
  "verb": "string",
  "auth_details": {
    "username": "string",
    "password": "string"
  },
  "auth_type": "basic",
  "content_type": "string",
  "field_set": "string",
  "settings": {
    "include_html": boolean
  }
}

Properties

Property	Description	Data type	Parameters	Required
event_types	The type of event that will trigger the newly registered webhook	enum (string)	sent delivered failed open click bounce unsubscribe resubscribe	Yes
url	The URL that will receive the webhook event	string	Valid URL	Yes
verb	The HTTP method that will be used by the webhook	enum (string)	get put post patch delete	Yes
auth_details	Authorization details required by the provided webhook URL.	JSON	username password	No
username	The username required by the provided webhook URL	string	Valid string	Yes, if auth_details is not empty
password	The username required by the provided webhook URL	string	Valid string	Yes, if auth_details is not empty
auth_type	The type of authorization used by the provided webhook URL	enum (string)	basic	Yes, if auth_details is not empty
content_type	The original media type (prior to any content encoding applied for sending) used for the webhook payload.	enum (string)	application/x-www-form-urlencoded application/json	No
field_set	The format of the webhook payload. Set to “legacy” to use the format of legacy transactional callbacks.	enum (string)	standard legacy	No
settings	Optional settings to be used for this webhook.	JSON	include_html	No
include_html	Setting to enable sending transactional email’s HTML content as part of webhook payload. HTML content is only sent as part of “sent” event types and only part of the “legacy” field set.	boolean	true false	No

Example Request

curl --location 'https://api.everlytic.net/transactional/email/v1/webhooks' \
--data '{
  "event_types": [
    "sent"
  ],
  "url": "https://your.webhook.url",
  "verb": "post",
  "auth_details": {
    "username": "admin",
    "password": "password123"
  },
  "auth_type": "basic",
  "content_type": "application/x-www-form-urlencoded",
  "field_set": "standard",
  "settings": {
    "include_html": true
  }
}'

Response

Status codes

Status code	Explanation
200 Ok	Webhook was created successfully
400 Bad Request	The request body was formatted improperly
401 Unauthorized	The provided authorization credentials are incorrect
412 Precondition Failed	One or more of the required fields were invalid

Properties

Properties of response with 200 Ok status

Property	Description	Data type	Parameters
webhook	Array containing response properties	JSON	id url verb auth_details auth_type status settings content_type field_set updated_timestamp created_timestamp event_types
id	The ID that will be used to identify the webhook in future requests	string
url	The URL that will receive the webhook event	string
verb	The HTTP method that will be used by the webhook	enum (string)	get put post patch delete
auth_details	Authorization details required by the provided webhook URL.	JSON	username password
username	The username required by the provided webhook URL	string
password	The password required by the provided webhook URL	string
auth_type	The type of authorization used by the provided webhook URL	enum (string)	basic
status	The current state of the new webhook	enum (string)	enabled disabled
settings	Optional settings used for this webhook.	JSON	include_html
include_html	Setting to enable sending transactional email’s HTML content as part of webhook payload. HTML content is only sent as part of “sent” event types and only part of the “legacy” field set.	boolean	true false
content_type	The original media type (prior to any content encoding applied for sending) used for the webhook payload.	enum (string)	application/x-www-form-urlencoded application/json
field_set	The format of the webhook payload. Set to “legacy” to use the format of legacy transactional callbacks.	enum (string)	standard legacy
updated_timestamp	The date and time that the webhook was last updated	date-time	ISO 8601 date-time string
created_timestamp	The date and time that the webhook was initially created	date-time	ISO 8601 date-time string
event_types	Array containing the type of event that will trigger the webhook	array (string)	sent delivered failed open click bounce unsubscribe resubscribe

Properties of response with status 4XX

Property	Description	Data type	Expected parameters
code	The HTTP response status code	integer	400 401 412
message	The reason for the failure	string	Valid string
error	Array containing errors field	JSON	errors
errors	Array containing the failure details	JSON	domain reason message locationType location
domain	The classification of the type of error	string	global usageLimit NoQuota
reason	Keyword used to describe the error	string	invalid invalidParameter UnverifiedDomain required Attachment Duplicate CustomHeaders NoQuota Suppressed RequestLimit ForbiddenAccess
message	Text describing the reason for the failure	string	Valid string
locationType	The location where the failure occurred	string	headers request body
location	The type of validation that failed	string	authorization sendValidation webhookValidation suppressionValidation templateValidation bouncesValidation trackedAttachmentsGroup trackedAttachmentsAsset default

Example Response

Successful request [200 OK]

{
  "webhook": {
    "id": “98765d91-fa6e-43f6-8e6a-1f6429fb285b",
    "url": "https://your.webhook.url",
    "verb": "post",
    "auth_details": null,
    "auth_type": "basic",
    "status": "enabled",
    "settings": "{\"include_html\":false}",
    "content_type": "application/json",
    "field_set": "standard",
    "updated_timestamp": "2023-08-07T14:04:25.000Z",
    "created_timestamp": "2022-01-31T11:22:50.000Z",
    "event_types": [
      "sent"
    ]
  }
}

Invalid/Missing authorization credentials [401 Unauthorized]

{
    "code": 401,
    "message": "Login Required",
    "error": {
        "errors": [
            {
                "domain": "global",
                "reason": "required",
                "message": "Login Required",
                "locationType": "request",
                "location": "authorization"
            }
        ]
    }
}

Unsuccessful request [412 Precondition Failed]

{
    "code": 412,
    "message": "The selected event types is invalid.",
    "error": {
        "errors": [
            {
                "domain": "global",
                "reason": "invalidParameter",
                "message": "The selected event types is invalid.",
                "locationType": "request",
                "location": "webhookValidation"
            }
        ]
    }
}