Create Webhook
Register a webhook endpoint to receive real-time event notifications
Authentication
Account API Key required via Authorization: Bearer {api_key} header.
Request Body
urlstringbodyrequiredHTTPS URL where webhook events will be delivered. Must use HTTPS protocol.
eventsarraybodyrequiredArray of event types to subscribe to. Must contain at least one event.
Available events:
message.received- New inbound email receivedmessage.bounced- Outbound message bouncedmessage.delivered- Outbound message successfully deliveredmessage.complained- Recipient marked message as spam
inbox_idstringbodyOptional inbox UUID. If provided, webhook will only receive events for this specific inbox. If null/omitted, receives events for all inboxes in the account.
curl -X POST https://api.daimon.email/v1/webhooks \
-H "Authorization: Bearer dm_free_7d8a9b0c1d2e3f4g5h6i7j8k9l0m1n2o" \
-H "Content-Type: application/json" \
-d '{
"url": "https://your-agent.com/webhook",
"events": ["message.received"],
"inbox_id": "inb_abc123"
}'import { DaimonClient } from 'daimon-email';
const client = new DaimonClient({
apiKey: 'dm_free_7d8a9b0c1d2e3f4g5h6i7j8k9l0m1n2o'
});
const webhook = await client.webhooks.create({
url: 'https://your-agent.com/webhook',
events: ['message.received'],
inboxId: 'inb_abc123'
});
console.log(`Webhook ID: ${webhook.id}`);
console.log(`Secret: ${webhook.secret}`); // Save this for HMAC verificationfrom daimon_email import DaimonClient
client = DaimonClient(api_key='dm_free_7d8a9b0c1d2e3f4g5h6i7j8k9l0m1n2o')
webhook = client.webhooks.create(
url='https://your-agent.com/webhook',
events=['message.received'],
inbox_id='inb_abc123'
)
print(f"Webhook ID: {webhook.id}")
print(f"Secret: {webhook.secret}") # Save this for HMAC verificationResponse
{
"result": {
"id": "wh_xyz789",
"account_id": "acc_def456",
"inbox_id": "inb_abc123",
"url": "https://your-agent.com/webhook",
"secret": "whsec_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
"events": ["message.received"],
"status": "active",
"last_delivered_at": null,
"failure_count": 0,
"created_at": "2024-03-11T14:23:45Z",
"updated_at": "2024-03-11T14:23:45Z"
},
"next_steps": [
"Save the secret to verify webhook signatures",
"Implement webhook handler at https://your-agent.com/webhook",
"Return HTTP 200 within 5 seconds to acknowledge receipt",
"See /api-reference/webhooks/test for HMAC signature verification examples"
]
}Response Fields
idstringUnique webhook identifier (prefix: wh_)
account_idstringAccount that owns this webhook
inbox_idstring | nullInbox this webhook is scoped to, or null for account-wide
urlstringHTTPS endpoint where events are delivered
secretstringHMAC signing secret for verifying webhook authenticity. Only returned on creation - save this value.
eventsarrayEvent types this webhook is subscribed to
statusstringWebhook health status:
active- Delivering events successfullyunhealthy- Multiple consecutive delivery failuresdisabled- Manually disabled via PATCH request
last_delivered_atstring | nullISO 8601 timestamp of last successful delivery
failure_countnumberConsecutive delivery failures. Webhook goes unhealthy after 5 failures.
created_atstringISO 8601 timestamp of webhook creation
updated_atstringISO 8601 timestamp of last update
Error Responses
400errorInvalid request - URL must be HTTPS, events array cannot be empty
401errorInvalid or missing API key
404errorInbox not found or does not belong to this account
Info
Important: The secret field is only returned on webhook creation. Store it securely - you'll need it to verify webhook signatures. If you lose it, you must delete and recreate the webhook.