Webhook Configuration

Configure real-time event subscriptions for your Dictionary API integration. Receive instant notifications when definitions are updated, translations complete, or API limits are reached.

New Webhook Endpoint

Add a new webhook URL to receive real-time events from Dictionary.

We will POST JSON payloads to this URL. Must be publicly accessible and support HTTPS.
Generate a secret to verify webhook signatures. If left empty, a default secret will be used.

Available Events

Dictionary emits the following event types. Subscribe to specific events or all events using `*`.

Event Name Description Frequency
word.added Triggered when a new word is successfully added to the Dictionary database. Medium
definition.updated Emitted when an existing word's definition, etymology, or usage examples are modified. Low
translation.completed Fired when an asynchronous bulk translation job finishes processing. Low
api.rate_limit.warning Sent when your API key approaches 80% or 95% of the hourly request quota. Critical
synonym.generated Triggered when AI generates and validates a new synonym relationship. High
user.dictionary.created Emitted when a user creates a new custom dictionary collection. Low

Payload Structure

All webhook payloads are sent as JSON with a consistent envelope structure. Below is an example of a definition.updated event.

JSON 
{
  "id": "evt_8f9a2b3c4d5e6f7g8h9i0j1k",
  "type": "definition.updated",
  "timestamp": "2025-03-15T14:32:18Z",
  "api_version": "v2.1",
  "data": {
    "word_id": "wrd_ephemeral_en",
    "word": "ephemeral",
    "language": "en",
    "changes": {
      "field": "definition",
      "old_value": "Lasting for a short time.",
      "new_value": "Lasting for a very short time; transitory or short-lived."
    },
    "source": "editorial_review",
    "editor_id": "usr_lex_9281"
  }
}
🔍 Note:

All payloads include a unique id for idempotency. We guarantee at-least-once delivery. Implement retry logic for timeouts.

Security & Verification

We sign every webhook payload to ensure authenticity. Verify signatures before processing events.

🔑 X-Signature-256

We append a cryptographic signature to each request header using your webhook secret. Verify it using HMAC-SHA256.

⏱️ Timestamp Validation

Each request includes an X-Timestamp header. Reject payloads older than 5 minutes to prevent replay attacks.

🔄 Automatic Retries

We retry failed deliveries up to 5 times with exponential backoff. Non-2xx responses trigger retries.

🛡️ IP Allowlisting

Filter incoming requests to our webhook IP ranges. Find our current CIDR blocks in the network documentation.

✅ Webhook configuration saved successfully!
}