Webhooks

About Webhooks

Webhooks allow you to receive real-time HTTP notifications whenever data is verified through Dymo API. Instead of polling for results, your server receives instant callbacks with verification details.

This feature is available exclusively for Pro Plan users in your Webhooks Dashboard.

Each webhook delivery costs 0.10 credits.

Creating a Webhook

To create a webhook, you need to provide:

1. Name: A unique identifier for your webhook (alphanumeric, hyphens, and underscores only)
2. URL: The endpoint where notifications will be sent (must be a public URL, localhost not allowed)
3. Filter Expression: Conditions that determine when the webhook triggers
4. Authentication (optional): API Key, Bearer Token, or Basic Auth
5. Custom Headers (optional): Additional headers to include in requests
6. App Filter (optional): Limit triggers to specific apps/API keys

Filter Expressions

Filter expressions determine when your webhook triggers. You can use the Selector mode (visual builder) or Manual mode (write expressions directly).

Available Fields

Operators

Logical Operators

• and - Both conditions must be true
• or - Either condition can be true
• not - Negates the condition

Functions

• lower(field) - Convert to lowercase
• upper(field) - Convert to uppercase
• len(field) - Get string length

Example Expressions

# Trigger for valid emails only
data.type eq "email" and data.valid eq true

# Trigger for fraud detection on any data type
data.fraud eq true

# Trigger for compromised or blocklisted data
plugins.compromised eq true or plugins.blocklist eq true

# Trigger for high risk scores
plugins.riskScore gt 70

# Trigger for low reputation emails
data.type eq "email" and plugins.reputation eq "low"

# Trigger for multiple data types
data.type in ["email", "phone", "ip"]

# Trigger for Gmail addresses with fraud
lower(data.value) contains "@gmail.com" and data.fraud eq true

Webhook Payload

When triggered, your endpoint receives a POST request with the following JSON payload:

{
  "webhook": "my-webhook-name",
  "event": "DATA_FRAUD",
  "timestamp": "2024-01-15T10:30:00.000Z",
  "userId": "user_123",
  "data": {
    "type": "email",
    "value": "[email protected]",
    "details": {
      "valid": true,
      "fraud": true,
      "plugins": {
        "riskScore": 85,
        "reputation": "low",
        "blocklist": false,
        "compromiseDetector": true
      }
    }
  }
}

Headers Included

Plus any authentication headers and custom headers you configured.

Authentication Options

None

No authentication headers are added.

API Key

Adds X-API-Key: your-api-key header.

Bearer Token

Adds Authorization: Bearer your-token header.

Basic Auth

Adds Authorization: Basic base64(username:password) header.

App Filtering

You can optionally restrict webhooks to only trigger for specific apps:

• No apps selected: Webhook triggers for ALL API keys (including keys without apps)
• Apps selected: Webhook only triggers for API keys linked to the selected apps

This is useful when you have different applications using the same Dymo API account and want separate webhook handling for each.

Limits

• Maximum 15 webhooks per account
• Webhook delivery timeout: 10 seconds
• Maximum URL length: 500 characters
• Maximum filter expression length: 2000 characters
• Maximum 5 custom headers per webhook

FAQs

Does this feature consume credits?

Yes, each successful webhook delivery costs 0.10 credits. Failed deliveries are not charged.

What happens if my endpoint is down?

If your endpoint returns a non-2xx status code or times out, the webhook delivery is marked as failed and no credits are deducted. There is no automatic retry.

Can I test my webhooks?

You can use services like webhook.site or requestbin.com to test your webhook configuration before pointing to your production endpoint.

What happens to my webhooks if I unsubscribe?

If you cancel your Pro plan, your webhooks will be deactivated. They will be reactivated if you resubscribe.

Related Pages

• Webhooks Dashboard
• Data Verifier
• Risk Score Plugin
• Blocklist Plugin