Create Webhook

POST https://api.echovalue.dev/webhook

Creates a new webhook.

Headers

Header	Description
`x-token`	Your API token
`Content-Type`	Must be `application/json`

Request

Common Fields

These fields are valid in both modes.

Field	Type	Description	Required
`webhookId`	string	Public webhook identifier used for management endpoints. Defaults to `default` when omitted.	No
`url`	string	Callback URL; must be HTTPS and publicly reachable.	Yes
`headers`	object	Custom headers to include in the callback request.	No

Inbound Email Webhook

Use this mode when you want echoValue to assign an opaque mailbox address and forward each inbound email to your webhook URL.

Mailbox-only fields

Field	Type	Description	Required
`format`	string	Native message format: `slack`, `discord`, `teams`, `telegram`, `pagerduty`, `custom`	No
`template`	object	JSON template for `custom` format. Max 2048 bytes, 5 nesting levels.	No
`options`	object	Format-specific options such as `chat_id` or `routing_key`	No
`includeAttachments`	boolean	Include email attachments in payloads. Default: `true`.	No

Need a temporary callback URL while testing? Use webhook.echovalue.dev and set the generated HTTPS URL as url.

Minimal request

{
  "webhookId": "support-alerts",
  "url": "https://hooks.slack.com/services/XXX/YYY/ZZZ",
  "format": "slack",
  "includeAttachments": false
}

Typical response

{
  "webhookId": "support-alerts",
  "webhook": "https://hooks.slack.com/services/XXX/YYY/ZZZ",
  "headers": {},
  "format": "slack",
  "options": {},
  "includeAttachments": false,
  "email": "r_abcd1234@hook.echovalue.dev",
  "hash": "a1b2c3d4e5f6..."
}

Notes

The response includes an opaque email mailbox address.
format, template, options, and includeAttachments are only valid in this mode.
Inbound email payloads are limited to 1 MiB after parsing.
See Webhook Inbound Email for end-to-end examples.

Scheduled Webhook

Use this mode when you want echoValue to call your webhook URL on a recurring schedule.

Schedule field

Field	Type	Description	Required
`schedule.cron`	string	5-field cron expression: `minute hour day month weekday`	Yes
`schedule.timezone`	string	IANA timezone used to evaluate the cron expression, for example `Europe/Rome`	Yes
`schedule.active`	boolean	Whether scheduled delivery is enabled. Default: `true`.	No

Use crontab.echovalue.dev to generate a valid value for schedule.cron.

Minimal request

{
  "webhookId": "daily-sync",
  "url": "https://example.com/hooks/daily-sync",
  "schedule": {
    "cron": "0 9 * * *",
    "timezone": "Europe/Rome"
  }
}

Typical response

{
  "webhookId": "daily-sync",
  "webhook": "https://example.com/hooks/daily-sync",
  "headers": {},
  "schedule": {
    "cron": "0 9 * * *",
    "timezone": "Europe/Rome",
    "active": true,
    "nextRunAt": "2026-04-24T07:00:00.000Z"
  },
  "hash": "a1b2c3d4e5f6..."
}

Notes

The response does not include an email field.
Do not send format, template, options, or includeAttachments together with schedule.
See Webhook Scheduled Jobs for end-to-end examples.

Response Fields

Field	Type	Description
`webhookId`	string	Public webhook identifier for management operations
`webhook`	string	Configured callback URL
`headers`	object	Custom headers
`format`	string	Native format, only returned for inbound email webhooks
`template`	object	Custom template, only returned when `format` is `custom`
`options`	object	Format options; sensitive values are redacted
`includeAttachments`	boolean	Returned only for inbound email webhooks
`schedule`	object	Returned only for scheduled webhooks
`email`	string	Opaque mailbox address, returned only for inbound email webhooks
`hash`	string	SHA256 hash of your token

Notes

A webhook is either mailbox-triggered or scheduled, never both.
The webhook URL must be HTTPS and publicly reachable.

Status Codes

Status	Meaning
`200`	Webhook created
`400`	Invalid URL, invalid field combination, or malformed request
`401`	Invalid token
`402`	Insufficient credits
`409`	`webhookId` already exists
`500`	Internal server error