Skip to main content
Webhooks

Get webhook by ID

Retrieves a single webhook by its unique identifier.

GET
/v2/webhooks/{id}

Path Parameters

  • id - The webhook ID (24-character ObjectId)

Response Format

Returns a webhook object with:

  • object - Always "webhook"
  • id - Unique webhook identifier
  • name - Human-readable webhook name
  • url - Webhook endpoint URL
  • description - Optional description
  • topics - Array of subscribed event topics
  • status - Current status ("active", "paused", "suspended")
  • requestConfig - Request configuration (timeout, headers)
  • lastStatus - Last delivery attempt status
  • health - Health metrics
  • createdAt - Creation timestamp
  • updatedAt - Last update timestamp

The response includes the webhook signing secret for payload verification.

Example

{
  "object": "webhook",
  "id": "507f1f77bcf86cd799439011",
  "name": "Production Webhook",
  "url": "https://example.com/webhooks",
  "description": "Handles all production events",
  "topics": ["post.created", "post.updated"],
  "status": "active",
  "requestConfig": {
    "timeoutMs": 5000,
    "headers": {}
  },
  "lastStatus": {
    "code": 200,
    "message": "Success",
    "timestamp": "2025-01-15T10:30:00.000Z"
  },
  "health": {
    "lastResponseTime": 150,
    "avgResponseTime": 200,
    "lastSuccessAt": "2025-01-15T10:30:00.000Z",
    "errorsSinceLastSuccess": 0,
    "consecutiveFailures": 0
  },
  "createdAt": "2025-01-01T00:00:00.000Z",
  "updatedAt": "2025-01-15T10:30:00.000Z"
}

Version Availability

This endpoint is only available in API version 2026-01-01.nova and newer.

Authorizations

Authorizationstringheaderrequired

API key as Bearer token. Use: Authorization: Bearer sk_...

Path Parameters

idstringrequired

Webhook unique identifier

Example: 507f1f77bcf86cd799439011

Headers

Featurebase-Versionenum<string>header

API version for this request. Defaults to your organization's configured API version if not specified.

Available options: 2026-08-19.orbit, 2026-01-01.nova, 2025-12-12.clover
Example: 2026-08-19.orbit

Response

application/json

Success

createdAtstringrequired

ISO timestamp when the webhook was created

Example: 2025-01-15T10:30:00.000Z
descriptionstring | nullrequired

Optional description of the webhook purpose

Example: Handles all production events
healthobjectrequired
idstringrequired

Unique identifier

Example: 507f1f77bcf86cd799439011
lastStatusobject | nullrequired

Last delivery attempt status

namestringrequired

Human-readable webhook name

Example: Production Webhook
objectenum<string>required

Object type identifier

Available options: webhook
Example: webhook
requestConfigobjectrequired
secretstringrequired

Webhook signing secret for verifying payloads

Example: whsec_abc123def456ghi789
statusenum<string>required

Current status of the webhook

Available options: active, paused, suspended
Example: active
topicsenum<string>[]required

Array of event topics the webhook subscribes to

updatedAtstringrequired

ISO timestamp when the webhook was last updated

Example: 2025-01-15T10:30:00.000Z
urlstringrequired

Webhook endpoint URL

Example: https://example.com/webhooks
versionstringrequired

API version for webhook payloads

Example: 1.0

Still need help? Ask the team