Skip to main content
PUT
Update Webhook

Authorizations

X-Account-ApiKey
string
header
required

This api key can be used for all account level operations

Path Parameters

webhook_id
integer
required

The unique ID of the webhook to update.

Example:

117

Body

application/json

Request body for updating an existing webhook. All fields are optional, including url. Only include fields you want to change: a field you leave out keeps its current value, and the defaults listed apply only on create. To remove the signing secret, send "secret": ""; the webhook is then delivered unsigned.

url
string<uri>
required

URL endpoint to receive webhook POST requests. Must:

  • Be an absolute http:// or https:// URL with a host. Anything else is rejected with HTTP 422. Use HTTPS: over plain HTTP, event data travels unencrypted.
  • Be publicly accessible
  • Return 2xx status within 10 seconds
  • Handle duplicate deliveries (use eventId for idempotency)
Example:

"https://app.hooli.com/api/webhooks/sendpost"

enabled
boolean
default:true

Whether the webhook is active immediately after creation. Set to false to configure and test before activating.

Example:

true

processed
boolean
default:false

Fire when email is accepted by SendPost API

Example:

false

sent
boolean
default:false

Fire when email is sent to recipient's mail server

Example:

false

delivered
boolean
default:true

Fire when email is accepted by recipient's mail server

Example:

true

dropped
boolean
default:true

Fire when email is not sent (suppression, invalid, etc.)

Example:

true

smtpDropped
boolean
default:false

Fire when email is rejected at SMTP level

Example:

false

softBounced
boolean
default:true

Fire on temporary delivery failure (will retry)

Example:

true

hardBounced
boolean
default:true

Fire on permanent delivery failure

Example:

true

opened
boolean
default:true

Fire when email is opened. Fires on EVERY open. Consider using uniqueOpen instead to reduce volume.

Example:

true

clicked
boolean
default:true

Fire when a link is clicked. Fires on EVERY click. Consider using uniqueClick instead to reduce volume.

Example:

true

unsubscribed
boolean
default:true

Fire when recipient clicks unsubscribe link

Example:

true

spam
boolean
default:true

Fire when recipient marks email as spam

Example:

true

uniqueOpen
boolean
default:false

Fire only on FIRST open of each email (unique opens). More efficient than opened if you only need engagement metrics.

Example:

false

uniqueClick
boolean
default:false

Fire only on FIRST click of each email (unique clicks). More efficient than clicked if you only need engagement metrics.

Example:

false

validated
boolean

Fire with the real-time list cleaning result of each email (Validation event, type 82). Needs the Real-Time List Cleaning add-on. Off unless set to true. On update, leaving this out keeps the current value. See Real-Time Validation Results.

Example:

false

secret
string

Signing secret for this webhook. When set, every request to the webhook carries X-SendPost-Signature, the hex-encoded HMAC-SHA256 of the raw request body keyed with this secret. Without a secret, requests are sent unsigned; your Account API Key is never used for signing. Leading and trailing spaces are removed. On update, leaving this out keeps the current secret and "" removes it. See Webhook Signature Verification.

Example:

"8f14e45fceea167a5a36dedd4bea2543"

eventSubOptions
object

Narrow which Dropped reasons and Validation results this webhook receives. Leave out dropped or validated and everything in it stays on. Inside either object, list every key: a key you leave out counts as false. On update, this replaces the stored options, so send both objects if you use both. Not returned in webhook responses.

Response

Webhook updated successfully.

Webhook configuration for receiving real-time email event notifications. When events occur (delivery, open, click, bounce, etc.), SendPost sends HTTP POST requests to your configured webhook URL.

Best Practices:

  • Use HTTPS endpoints for security
  • Respond with 2xx status within 10 seconds
  • Implement idempotency using eventId
  • Verify webhook signatures (see documentation)
id
integer<int64>

Unique identifier for the webhook configuration

Example:

117

enabled
boolean

Whether the webhook is active. When false, no events will be sent to this webhook. Useful for temporarily pausing notifications during maintenance.

Example:

true

url
string<uri>

HTTPS endpoint URL to receive webhook POST requests. Must be publicly accessible and return 2xx status code.

Example:

"https://app.hooli.com/api/webhooks/sendpost"

processed
boolean

Trigger webhook when an email is accepted for processing. Fires immediately when API call is successful.

Example:

true

sent
boolean

Trigger webhook when an email is sent to the recipient's mail server. Indicates the email left SendPost's infrastructure.

Example:

true

dropped
boolean

Trigger webhook when an email is dropped before sending. Common reasons: suppressed address, invalid email, unverified domain.

Example:

true

smtpDropped
boolean

Trigger webhook when an email is dropped at SMTP level. Usually due to policy rejection by receiving server.

Example:

false

delivered
boolean

Trigger webhook when an email is successfully delivered. Note: "Delivered" means accepted by mail server, not inbox placement.

Example:

true

softBounced
boolean

Trigger webhook on temporary delivery failure (soft bounce). SendPost will retry delivery automatically.

Example:

true

hardBounced
boolean

Trigger webhook on permanent delivery failure (hard bounce). The recipient is automatically added to suppression list.

Example:

true

opened
boolean

Trigger webhook when recipient opens the email. Fires on every open (can fire multiple times per email).

Example:

true

clicked
boolean

Trigger webhook when recipient clicks a link. Fires on every click (can fire multiple times per email).

Example:

true

unsubscribed
boolean

Trigger webhook when recipient clicks the unsubscribe link. The recipient is automatically added to suppression list.

Example:

true

spam
boolean

Trigger webhook when recipient marks email as spam. The recipient is automatically added to suppression list. Monitor this closely - high spam rates damage sender reputation.

Example:

true

uniqueOpen
boolean

Trigger webhook only on the first open of an email (unique opens). Use this instead of 'opened' if you only care about unique engagement.

Example:

false

uniqueClick
boolean

Trigger webhook only on the first click of an email (unique clicks). Use this instead of 'clicked' if you only care about unique engagement.

Example:

false

validated
boolean

Trigger webhook with the real-time list cleaning result of each email (Validation event, type 82). Needs the Real-Time List Cleaning add-on. Only present in responses when true. See Real-Time Validation Results.

Example:

true

status
enum<string>

Health status of the webhook (read-only):

  • active - delivering normally
  • degraded - recent delivery failures
  • disabled - auto-disabled after repeated consecutive failures
Available options:
active,
degraded,
disabled
Example:

"active"

disabledAt
integer<int64>

UNIX epoch timestamp in nanoseconds when the webhook was auto-disabled (0 if never). Read-only.

Example:

0

disabledReason
string

Human-readable reason the webhook was auto-disabled (empty if active). Read-only.

Example:

""

created
integer<int64>

UNIX epoch timestamp in nanoseconds when the webhook was created

Example:

1704067200000000000