Docs/Webhooks

Webhooks

Receive real-time HTTP POST notifications when events occur in your EdgeURL account

Overview

Webhooks allow your server to receive automatic HTTP POST requests whenever specific events occur in your EdgeURL account. Configure webhooks from your Dashboard to integrate EdgeURL with your own systems.

Each webhook subscription includes a unique secret used for signature verification. You can subscribe to one or more event types per webhook endpoint.

Event Types

link.created

Triggered when a new short link is created.

Payload Data

{ "id": "uuid", "slug": "my-link", "short_url": "https://0gr.me/my-link", "target_url": "https://example.com/page", "created_at": "2025-01-15T10:30:00Z" }

link.updatedPlanned

Triggered when a link is modified (target URL change, activation toggle, etc). This event is defined but not yet actively fired. Subscribe now to receive it automatically when enabled.

Payload Data

{ "id": "uuid", "slug": "my-link", "short_url": "https://0gr.me/my-link", "target_url": "https://example.com/new-page", "updated_at": "2025-01-15T11:00:00Z" }

link.deletedPlanned

Triggered when a link is permanently deleted. This event is defined but not yet actively fired. Subscribe now to receive it automatically when enabled.

Payload Data

{ "id": "uuid", "slug": "my-link" }

link.clicked

Triggered when a short link receives a click. Includes geo and device data when available.

Payload Data

{ "link_id": "uuid", "short_url": "https://0gr.me/my-link", "target_url": "https://example.com/page", "click": { "country": "US", "city": "San Francisco", "device": "mobile", "browser": "Chrome", "referrer": "https://twitter.com" } }

Full Payload Structure

Every webhook delivery wraps the event-specific data in a standard envelope:

{ "event": "link.clicked", "timestamp": "2025-01-15T10:30:00Z", "data": { // Event-specific data (see above) } }

HTTP Headers

Every webhook HTTP request includes these headers:

Content-Type

application/json

X-EdgeURL-Signature

HMAC-SHA256 hex digest of the JSON payload body

X-EdgeURL-Event

The event type (e.g. link.created, link.clicked)

X-EdgeURL-Delivery-Attempt

Delivery attempt number (starts at 1, increments on retries)

User-Agent

EdgeURL-Webhooks/1.0

Signature Verification

Every webhook request is signed using HMAC-SHA256 with your webhook secret. Always verify the signature to ensure the request originated from EdgeURL.

Verification Steps

Read the raw request body as a string
Compute an HMAC-SHA256 hex digest using your webhook secret as the key
Compare the computed digest to the X-EdgeURL-Signature header value using a timing-safe comparison

Node.js Example

Security: Always use a timing-safe comparison (crypto.timingSafeEqual) to prevent timing attacks. Never use simple string equality (===) for signature verification.

Retry Behavior

Failed webhook deliveries are automatically retried with exponential backoff. A delivery is considered failed if your endpoint returns a non-2xx status code or the request times out (10 second timeout).

Retry Schedule

Retry 1After 1 minute

Retry 2After 5 minutes

Retry 3After 15 minutes

Retry 4After 1 hour

Retry 5 (final)After 6 hours

After 5 failed retries, the delivery is marked as permanently failed. All delivery attempts are logged and visible in the dashboard.

Best Practice: Your webhook endpoint should respond with a 200 status code within 10 seconds. Process the event asynchronously if it requires longer handling.

Delivery Logging

Every delivery attempt is logged in the edgeurl_webhook_deliveries table, including:

Event type and full payload
Delivery status (delivered or failed)
HTTP response status code
Response body (for debugging)
Retry count and next retry time
Timestamps for delivery and retry attempts

Next Steps

→ Configure Webhooks in Dashboard → API Reference → Local Development Guide

Docs/Webhooks

Webhooks

Receive real-time HTTP POST notifications when events occur in your EdgeURL account

Overview

Each webhook subscription includes a unique secret used for signature verification. You can subscribe to one or more event types per webhook endpoint.

Event Types

link.created

Triggered when a new short link is created.

Payload Data

{ "id": "uuid", "slug": "my-link", "short_url": "https://0gr.me/my-link", "target_url": "https://example.com/page", "created_at": "2025-01-15T10:30:00Z" }

link.updatedPlanned

Triggered when a link is modified (target URL change, activation toggle, etc). This event is defined but not yet actively fired. Subscribe now to receive it automatically when enabled.

Payload Data

{ "id": "uuid", "slug": "my-link", "short_url": "https://0gr.me/my-link", "target_url": "https://example.com/new-page", "updated_at": "2025-01-15T11:00:00Z" }

link.deletedPlanned

Triggered when a link is permanently deleted. This event is defined but not yet actively fired. Subscribe now to receive it automatically when enabled.

Payload Data

{ "id": "uuid", "slug": "my-link" }

link.clicked

Triggered when a short link receives a click. Includes geo and device data when available.

Payload Data

Full Payload Structure

Every webhook delivery wraps the event-specific data in a standard envelope:

{ "event": "link.clicked", "timestamp": "2025-01-15T10:30:00Z", "data": { // Event-specific data (see above) } }

HTTP Headers

Every webhook HTTP request includes these headers:

Content-Type

application/json

X-EdgeURL-Signature

HMAC-SHA256 hex digest of the JSON payload body

X-EdgeURL-Event

The event type (e.g. link.created, link.clicked)

X-EdgeURL-Delivery-Attempt

Delivery attempt number (starts at 1, increments on retries)

User-Agent

EdgeURL-Webhooks/1.0

Signature Verification

Every webhook request is signed using HMAC-SHA256 with your webhook secret. Always verify the signature to ensure the request originated from EdgeURL.

Verification Steps

Read the raw request body as a string
Compute an HMAC-SHA256 hex digest using your webhook secret as the key
Compare the computed digest to the X-EdgeURL-Signature header value using a timing-safe comparison

Node.js Example

Security: Always use a timing-safe comparison (crypto.timingSafeEqual) to prevent timing attacks. Never use simple string equality (===) for signature verification.

Retry Behavior

Retry Schedule

Retry 1After 1 minute

Retry 2After 5 minutes

Retry 3After 15 minutes

Retry 4After 1 hour

Retry 5 (final)After 6 hours

After 5 failed retries, the delivery is marked as permanently failed. All delivery attempts are logged and visible in the dashboard.

Best Practice: Your webhook endpoint should respond with a 200 status code within 10 seconds. Process the event asynchronously if it requires longer handling.

Delivery Logging

Every delivery attempt is logged in the edgeurl_webhook_deliveries table, including:

Event type and full payload
Delivery status (delivered or failed)
HTTP response status code
Response body (for debugging)
Retry count and next retry time
Timestamps for delivery and retry attempts

Next Steps

→ Configure Webhooks in Dashboard → API Reference → Local Development Guide