Skip to main content
POST
AhaSend Go SDK
The AhaSend API creates a new webhook for event notifications. A scoped webhook requires at least one domain and the key must have write permission for every supplied domain. A global webhook requires webhooks:write:all; supplied domains are accepted but ignored, and the response contains domains: []. Contact events (the on_contact_* fields) are available only to accounts with the marketing features: turning one on for another account returns HTTP 400. A webhook with any contact event on needs an API key with contacts:read, and with lists:read as well for on_contact_added_to_list, on_contact_removed_from_list, on_contact_subscribed, on_contact_unsubscribed, and on_contact_complained; without them the request returns HTTP 403. The marketing check runs first.

Authorizations

Authorization
string
header
required

API key for authentication. Non-empty Security Requirement values are AhaSend API-key roles. Roles listed within one requirement object are jointly required; separate requirement objects are alternatives.

Headers

Idempotency-Key
string

Optional idempotency key for safe request retries. Must be a unique string for each logical request. An identical request with a completed stored outcome returns the original status and body. An in-progress execution returns 409, a changed method/path/body returns 422, and a released 5xx execution may run again. Keys for non-secret responses expire after 24 hours. API-key create responses include a one-time secret_key, so successful encrypted replay responses for those operations expire after 5 minutes.

Maximum string length: 255

Path Parameters

account_id
string<uuid>
required

Account ID

Body

application/json
name
string
required

Webhook name

Maximum string length: 255
url
string<uri>
required

Webhook URL

scope
enum<string>
required

Webhook scope

Available options:
global,
scoped
enabled
boolean
default:true

Whether the webhook is enabled

on_reception
boolean
default:false

Trigger on message reception

on_delivered
boolean
default:false

Trigger on message delivery

on_transient_error
boolean
default:false

Trigger on transient errors

on_failed
boolean
default:false

Trigger on permanent failures

on_bounced
boolean
default:false

Trigger on bounces

on_suppressed
boolean
default:false

Trigger on suppressions

on_opened
boolean
default:false

Trigger on opens

on_clicked
boolean
default:false

Trigger on clicks

on_unsubscribed
boolean
default:false

Trigger on unsubscribes

on_complained
boolean
default:false

Trigger on spam complaints

on_suppression_created
boolean
default:false

Trigger on suppression creation

on_suppression_deleted
boolean
default:false

Trigger on suppression deletion

on_dns_error
boolean
default:false

Trigger on DNS errors

on_contact_created
boolean
default:false

Trigger on contact creation

on_contact_updated
boolean
default:false

Trigger on contact updates

on_contact_deleted
boolean
default:false

Trigger on contact deletion

on_contact_added_to_list
boolean
default:false

Trigger when a contact is added to a list

on_contact_removed_from_list
boolean
default:false

Trigger when a contact is removed from a list

on_contact_subscribed
boolean
default:false

Trigger when a contact subscribes

on_contact_unsubscribed
boolean
default:false

Trigger when a contact unsubscribes

on_contact_complained
boolean
default:false

Trigger when a contact reports spam

origins
enum<string>[] | null

The origins of the contact and suppression events that the webhook gets. Omit it or send null for every origin. An empty array is refused with HTTP 400: to stop contact or suppression events, turn them off. An array that holds all four origins is saved as null, so that an origin added later reaches the webhook too. Message events and domain.dns_error have no origin, and the webhook always gets them.

Minimum array length: 1

Who made a change that a contact or suppression event reports: recipient for the contact or recipient, through an unsubscribe link, a one-click unsubscribe, or a spam complaint; api for you, through the AhaSend API; dashboard for you, through the AhaSend dashboard; system for AhaSend, for example after a bounce, an expired message or an email validation, or when AhaSend support makes the change.

Available options:
recipient,
api,
dashboard,
system
domains
string[] | null

For scoped, a non-empty array is required. For global, this may be omitted, null, empty, or non-empty; supplied values are accepted but ignored.

Response

Webhook created successfully

object
enum<string>
required

Object type identifier

Available options:
webhook
id
string<uuid>
required

Unique identifier for the webhook

created_at
string<date-time>
required

When the webhook was created

updated_at
string<date-time>
required

When the webhook was last updated

name
string
required

Webhook name

url
string<uri>
required

Webhook URL

enabled
boolean
required

Whether the webhook is enabled

on_reception
boolean
required

Trigger on message reception

on_delivered
boolean
required

Trigger on message delivery

on_transient_error
boolean
required

Trigger on transient errors

on_failed
boolean
required

Trigger on permanent failures

on_bounced
boolean
required

Trigger on bounces

on_suppressed
boolean
required

Trigger on suppressions

on_opened
boolean
required

Trigger on opens

on_clicked
boolean
required

Trigger on clicks

on_unsubscribed
boolean
required

Trigger on unsubscribes

on_complained
boolean
required

Trigger on spam complaints

on_suppression_created
boolean
required

Trigger on suppression creation

on_suppression_deleted
boolean
required

Trigger on suppression deletion

on_dns_error
boolean
required

Trigger on DNS errors

on_contact_created
boolean
required

Trigger on contact creation

on_contact_updated
boolean
required

Trigger on contact updates

on_contact_deleted
boolean
required

Trigger on contact deletion

on_contact_added_to_list
boolean
required

Trigger when a contact is added to a list

on_contact_removed_from_list
boolean
required

Trigger when a contact is removed from a list

on_contact_subscribed
boolean
required

Trigger when a contact subscribes

on_contact_unsubscribed
boolean
required

Trigger when a contact unsubscribes

on_contact_complained
boolean
required

Trigger when a contact reports spam

origins
enum<string>[] | null
required

The origins of the contact and suppression events that the webhook gets, or null for every origin. Message events and domain.dns_error have no origin, and the webhook always gets them.

Who made a change that a contact or suppression event reports: recipient for the contact or recipient, through an unsubscribe link, a one-click unsubscribe, or a spam complaint; api for you, through the AhaSend API; dashboard for you, through the AhaSend dashboard; system for AhaSend, for example after a bounce, an expired message or an email validation, or when AhaSend support makes the change.

Available options:
recipient,
api,
dashboard,
system
scope
enum<string>
required

Webhook scope

Available options:
global,
scoped
domains
string[]
required

Domains this webhook applies to. Always present; global webhooks return an empty array.

success_count
integer
required

Number of successful calls

Required range: x >= 0
error_count
integer
required

Number of unsuccessful calls

Required range: x >= 0
errors_since_last_success
integer
required

Number of consecutive failed calls. Reset to zero by the next successful call.

Required range: x >= 0
last_request_at
string<date-time> | null
required

When the webhook was last called

secret
string
required

Webhook signing secret. Returned only when the webhook is created.