Skip to content
VaartixVaartix Docs

Create a webhook endpoint

POST
/webhooks
curl --request POST \
  --url https://api.vaartix.com/webhooks \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "url": "https://api.acme.in/webhooks/vaartix", "events": [ "email.delivered", "email.bounced", "email.complained" ] }'

Vaartix sends a signed POST to the URL for each event you choose. The response includes the signing secret once; store it to verify requests. A team can have up to 10 endpoints.

Authorizations

Section titled “Authorizations”

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json
object
url
required

A public https:// URL.

string format: uri

Example 

https://api.acme.in/webhooks/vaartix
events
required
Array<string>
>= 1 items
Allowed values: email.sent email.delivered email.delivery_delayed email.bounced email.complained email.rejected email.rendering_failure email.suppressed email.opened email.clicked

Example 

[
  "email.delivered",
  "email.bounced",
  "email.complained"
]

Responses

Section titled “Responses”

201

Section titled “201”

The new endpoint, including its signing secret.

Media typeapplication/json
object
id
string
url
string format: uri
events
Array<string>
Allowed values: email.sent email.delivered email.delivery_delayed email.bounced email.complained email.rejected email.rendering_failure email.suppressed email.opened email.clicked
status

Endpoints are turned off automatically after 5 deliveries in a row fail every attempt.

string
Allowed values: enabled disabled
createdAt
string format: date-time
secret
required

The signing secret. Shown only when created or rotated.

string

Example 

{
  "id": "wh_4n8x2k7q1m9c3v5d",
  "events": [
    "email.sent"
  ],
  "status": "enabled",
  "secret": "whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw"
}

400

Section titled “400”

validation_error: the request is invalid. The message says which field and why.

Media typeapplication/json
object
error
required
object
type
required

Stable, machine-readable error type.

string
Allowed values: validation_error unauthorized forbidden not_found conflict rate_limited daily_quota_exceeded domain_not_verified invalid_from_address account_paused domain_needs_review content_rejected idempotency_conflict bad_request internal_error
message
required

Human-readable explanation, safe to show to developers.

string

Example 

{
  "error": {
    "type": "validation_error",
    "message": "to: \"priya@\" is not a valid email address."
  }
}

401

Section titled “401”

unauthorized: the API key is missing, invalid or revoked.

Media typeapplication/json
object
error
required
object
type
required

Stable, machine-readable error type.

string
Allowed values: validation_error unauthorized forbidden not_found conflict rate_limited daily_quota_exceeded domain_not_verified invalid_from_address account_paused domain_needs_review content_rejected idempotency_conflict bad_request internal_error
message
required

Human-readable explanation, safe to show to developers.

string

Example 

{
  "error": {
    "type": "validation_error"
  }
}

403

Section titled “403”

forbidden: the key cannot do this, for example a send-only key on a management endpoint.

Media typeapplication/json
object
error
required
object
type
required

Stable, machine-readable error type.

string
Allowed values: validation_error unauthorized forbidden not_found conflict rate_limited daily_quota_exceeded domain_not_verified invalid_from_address account_paused domain_needs_review content_rejected idempotency_conflict bad_request internal_error
message
required

Human-readable explanation, safe to show to developers.

string

Example 

{
  "error": {
    "type": "validation_error"
  }
}

409

Section titled “409”

conflict: the request clashes with the current state, for example too many endpoints.

Media typeapplication/json
object
error
required
object
type
required

Stable, machine-readable error type.

string
Allowed values: validation_error unauthorized forbidden not_found conflict rate_limited daily_quota_exceeded domain_not_verified invalid_from_address account_paused domain_needs_review content_rejected idempotency_conflict bad_request internal_error
message
required

Human-readable explanation, safe to show to developers.

string

Example 

{
  "error": {
    "type": "validation_error"
  }
}