Destinations API

Manage forwarding destinations for your capture endpoints

A destination is a URL that Hookdrop forwards captured webhook events to. When a new event arrives at your capture URL, Hookdrop automatically delivers it to every destination configured for that endpoint.

If a delivery fails, Hookdrop retries with exponential backoff. Each delivery attempt has a 10-second timeout.

---

List destinations

GET /api/endpoints/:id/destinations

Returns all forwarding destinations configured for an endpoint.

id · string · required

The endpoint ID.

cURL

curl https://hookdrop.dev/api/endpoints/ep_01hx9k2z3mq8p4j6n7r5st0vwu/destinations \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Response

id · string

Unique identifier for the destination.

url · string

The URL events are forwarded to.

secret · string

Optional signing secret. When set, Hookdrop signs each forwarded request so your server can verify it came from Hookdrop.

created_at · string

ISO 8601 timestamp of when the destination was added.

[
  {
    "id": "dst_01hx9m3z4nr9q5k7o8s6tu1wxv",
    "url": "https://your-server.com/webhooks",
    "secret": "whsec_••••••••••••••••",
    "created_at": "2024-05-12T11:00:00.000Z"
  }
]

---

Add a destination

POST /api/endpoints/:id/destinations

Adds a forwarding destination to an endpoint. Events captured after this point are forwarded to the new URL automatically.

id · string · required

The endpoint ID.

url · string · required

The URL to forward events to. Must be publicly reachable over HTTPS.

secret · string

Optional signing secret. Hookdrop uses this to sign forwarded requests so your server can verify their authenticity.

cURL

curl -X POST https://hookdrop.dev/api/endpoints/ep_01hx9k2z3mq8p4j6n7r5st0vwu/destinations \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-server.com/webhooks",
    "secret": "optional-signing-secret"
  }'

Response

{
  "id": "dst_01hx9m3z4nr9q5k7o8s6tu1wxv",
  "url": "https://your-server.com/webhooks",
  "secret": "whsec_••••••••••••••••",
  "created_at": "2024-05-12T11:00:00.000Z"
}

Hookdrop retries failed deliveries with exponential backoff. Each attempt times out after 10 seconds. You can inspect delivery attempts for any event using the Events API.

---

Remove a destination

DELETE /api/endpoints/:id/destinations/:destinationId

Removes a forwarding destination from an endpoint. Events already in flight are not affected, but no new events will be forwarded to this URL.

id · string · required

The endpoint ID.

destinationId · string · required

The destination ID to remove.

cURL

curl -X DELETE https://hookdrop.dev/api/endpoints/ep_01hx9k2z3mq8p4j6n7r5st0vwu/destinations/dst_01hx9m3z4nr9q5k7o8s6tu1wxv \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Response

Returns 204 No Content on success.