Webhook Subscribers¶

Create a webhook subscriber¶

POST /webhook-subscribers

Code samples

curl -X POST https://localhost:9543/api/v0.9/webhook-subscribers \
  -u {username}:{password} \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}' \
  -d @payload.json

Registers a webhook subscriber for the organization. Event deliveries (apikey., subscription., etc.) matching the subscriber's events filter are fanned out to its target URL. The secret, if provided, is encrypted at rest using AES-256-GCM.

Payload

{
  "id": "production-gateway",
  "displayName": "Production Gateway",
  "targetUrl": "https://gateway.example.com/devportal-webhook",
  "secret": "<shared-secret>",
  "publicKey": "string",
  "events": [
    "apikey.*",
    "subscription.*"
  ],
  "enabled": true,
  "timeoutMs": 5000
}

Authentication¶

Parameters

Name	In	Type	Required	Description
body	body	WebhookSubscriberRequest	true	Webhook subscriber configuration payload.

Example responses

201 Response

{
  "id": "production-gateway",
  "orgId": "org-12345",
  "displayName": "Production Gateway",
  "targetUrl": "https://gateway.example.com/devportal-webhook",
  "enabled": true,
  "events": [
    "apikey.*",
    "subscription.*"
  ],
  "timeoutMs": 5000,
  "hasSecret": true,
  "hasPublicKey": false,
  "createdBy": "[email protected]",
  "updatedBy": "[email protected]",
  "createdAt": "2019-08-24T14:15:22Z",
  "updatedAt": "2019-08-24T14:15:22Z"
}

Bad request. Validation and other bad-request errors are returned as a standard error object (field-level details, when present, are carried in its errors array); some legacy handlers return a message-only object.

{
  "status": "error",
  "code": "MISSING_REQUIRED_PARAMETER",
  "message": "Missing required parameter."
}

{
  "message": "Missing or invalid fields in the request payload"
}

409 Response

{
  "status": "error",
  "code": "CONFLICT",
  "message": "Conflict"
}

500 Response

{
  "status": "error",
  "code": "INTERNAL_SERVER_ERROR",
  "message": "An unexpected error occurred."
}

Responses

Status	Meaning	Description	Schema
201	Created	Webhook subscriber configuration response.	WebhookSubscriberResponseSchema
400	Bad Request	Bad request. Validation and other bad-request errors are returned as a standard error object (field-level details, when present, are carried in its `errors` array); some legacy handlers return a message-only object.	Inline
409	Conflict	The request conflicts with an existing resource.	ErrorResponse
500	Internal Server Error	Internal server error.	ErrorResponse

Response Schema

Enumerated Values

Property	Value
status	error

Response Headers¶

Status	Header	Type	Format	Description
201	Location	string	uri	URL of the created webhook subscriber.

List webhook subscribers¶

GET /webhook-subscribers

Code samples

curl -X GET https://localhost:9543/api/v0.9/webhook-subscribers \
  -u {username}:{password} \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'

Returns all webhook subscriber configurations for the organization. Secrets are never included in the response.

Authentication¶

Parameters

Name	In	Type	Required	Description
limit	query	integer	false	Maximum number of records to return.
offset	query	integer	false	Number of records to skip before returning results.

Example responses

200 Response

{
  "list": [
    {
      "id": "production-gateway",
      "orgId": "org-12345",
      "displayName": "Production Gateway",
      "targetUrl": "https://gateway.example.com/devportal-webhook",
      "enabled": true,
      "events": [
        "apikey.*",
        "subscription.*"
      ],
      "timeoutMs": 5000,
      "hasSecret": true,
      "hasPublicKey": false,
      "createdBy": "[email protected]",
      "updatedBy": "[email protected]",
      "createdAt": "2019-08-24T14:15:22Z",
      "updatedAt": "2019-08-24T14:15:22Z"
    }
  ],
  "count": 1,
  "pagination": {
    "total": 42,
    "limit": 20,
    "offset": 0
  }
}

500 Response

{
  "status": "error",
  "code": "INTERNAL_SERVER_ERROR",
  "message": "An unexpected error occurred."
}

Responses

Status	Meaning	Description	Schema
200	OK	List of webhook subscriber configurations.	Inline
500	Internal Server Error	Internal server error.	ErrorResponse

Response Schema

Status Code 200

Name	Type	Required	Restrictions	Description
» list	[WebhookSubscriberResponseSchema]	false	none	[Webhook subscriber configuration. The secret is never included.]
»» id	string	false	none	The webhook subscriber's handle (unique per org). Not the internal database uuid.
»» orgId	string	false	none	none
»» displayName	string	false	none	none
»» targetUrl	string(uri)	false	none	none
»» enabled	boolean	false	none	none
»» events	[string]	false	none	none
»» timeoutMs	integer	false	none	none
»» hasSecret	boolean	false	none	Whether a secret is configured for HMAC-signing outgoing payloads.
»» hasPublicKey	boolean	false	none	Whether a public key is configured for envelope-encrypting secret event payloads.
»» createdBy	string	false	none	Identity of the user who created this webhook subscriber, or `deleted_user` if that user's IDP reference no longer exists. Present on single-resource GET responses and list items.
»» updatedBy	string	false	none	Identity of the user who last updated this webhook subscriber, or `deleted_user` if that user's IDP reference no longer exists. Present on single-resource GET responses only, omitted on list items.
»» createdAt	string(date-time)	false	none	none
»» updatedAt	string(date-time)	false	none	none
» count	integer	false	none	Number of items returned in this page.
» pagination	Pagination	false	none	Standard pagination metadata returned with collection responses.
»» total	integer	true	none	Total number of records matching the query.
»» limit	integer	true	none	Maximum number of records returned in this response.
»» offset	integer	true	none	Number of records skipped before this page.

Get a webhook subscriber¶

GET /webhook-subscribers/{subscriberId}

Code samples

curl -X GET https://localhost:9543/api/v0.9/webhook-subscribers/{subscriberId} \
  -u {username}:{password} \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'

Retrieves a single webhook subscriber configuration by ID.

Authentication¶

Parameters

Name	In	Type	Required	Description
subscriberId	path	string	true	The webhook subscriber's handle (its `id` in request/response payloads), not the internal database uuid.

Example responses

200 Response

{
  "id": "production-gateway",
  "orgId": "org-12345",
  "displayName": "Production Gateway",
  "targetUrl": "https://gateway.example.com/devportal-webhook",
  "enabled": true,
  "events": [
    "apikey.*",
    "subscription.*"
  ],
  "timeoutMs": 5000,
  "hasSecret": true,
  "hasPublicKey": false,
  "createdBy": "[email protected]",
  "updatedBy": "[email protected]",
  "createdAt": "2019-08-24T14:15:22Z",
  "updatedAt": "2019-08-24T14:15:22Z"
}

404 Response

{
  "status": "error",
  "code": "ORG_NOT_FOUND",
  "message": "Organization not found."
}

500 Response

{
  "status": "error",
  "code": "INTERNAL_SERVER_ERROR",
  "message": "An unexpected error occurred."
}

Responses

Status	Meaning	Description	Schema
200	OK	Webhook subscriber configuration response.	WebhookSubscriberResponseSchema
404	Not Found	Resource not found.	ErrorResponse
500	Internal Server Error	Internal server error.	ErrorResponse

Update a webhook subscriber¶

PUT /webhook-subscribers/{subscriberId}

Code samples

curl -X PUT https://localhost:9543/api/v0.9/webhook-subscribers/{subscriberId} \
  -u {username}:{password} \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}' \
  -d @payload.json

Updates an existing webhook subscriber configuration. Only supplied fields are updated; omitted fields retain their stored values.

Payload

{
  "id": "production-gateway",
  "displayName": "Production Gateway",
  "targetUrl": "https://gateway.example.com/devportal-webhook",
  "secret": "<shared-secret>",
  "publicKey": "string",
  "events": [
    "apikey.*",
    "subscription.*"
  ],
  "enabled": true,
  "timeoutMs": 5000
}

Authentication¶

Parameters

Name	In	Type	Required	Description
body	body	WebhookSubscriberRequest	false	Webhook subscriber update payload. All fields are optional; only supplied fields are updated.
subscriberId	path	string	true	The webhook subscriber's handle (its `id` in request/response payloads), not the internal database uuid.

Example responses

200 Response

{
  "id": "production-gateway",
  "orgId": "org-12345",
  "displayName": "Production Gateway",
  "targetUrl": "https://gateway.example.com/devportal-webhook",
  "enabled": true,
  "events": [
    "apikey.*",
    "subscription.*"
  ],
  "timeoutMs": 5000,
  "hasSecret": true,
  "hasPublicKey": false,
  "createdBy": "[email protected]",
  "updatedBy": "[email protected]",
  "createdAt": "2019-08-24T14:15:22Z",
  "updatedAt": "2019-08-24T14:15:22Z"
}

Bad request. Validation and other bad-request errors are returned as a standard error object (field-level details, when present, are carried in its errors array); some legacy handlers return a message-only object.

{
  "status": "error",
  "code": "MISSING_REQUIRED_PARAMETER",
  "message": "Missing required parameter."
}

{
  "message": "Missing or invalid fields in the request payload"
}

404 Response

{
  "status": "error",
  "code": "ORG_NOT_FOUND",
  "message": "Organization not found."
}

409 Response

{
  "status": "error",
  "code": "CONFLICT",
  "message": "Conflict"
}

500 Response

{
  "status": "error",
  "code": "INTERNAL_SERVER_ERROR",
  "message": "An unexpected error occurred."
}

Responses

Status	Meaning	Description	Schema
200	OK	Webhook subscriber configuration response.	WebhookSubscriberResponseSchema
400	Bad Request	Bad request. Validation and other bad-request errors are returned as a standard error object (field-level details, when present, are carried in its `errors` array); some legacy handlers return a message-only object.	Inline
404	Not Found	Resource not found.	ErrorResponse
409	Conflict	The request conflicts with an existing resource.	ErrorResponse
500	Internal Server Error	Internal server error.	ErrorResponse

Response Schema

Enumerated Values

Property	Value
status	error

Delete a webhook subscriber¶

DELETE /webhook-subscribers/{subscriberId}

Code samples

curl -X DELETE https://localhost:9543/api/v0.9/webhook-subscribers/{subscriberId} \
  -u {username}:{password} \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'

Deletes a webhook subscriber configuration by ID.

Authentication¶

Parameters

Name	In	Type	Required	Description
subscriberId	path	string	true	The webhook subscriber's handle (its `id` in request/response payloads), not the internal database uuid.

Example responses

404 Response

{
  "status": "error",
  "code": "ORG_NOT_FOUND",
  "message": "Organization not found."
}

500 Response

{
  "status": "error",
  "code": "INTERNAL_SERVER_ERROR",
  "message": "An unexpected error occurred."
}

Responses

Status	Meaning	Description	Schema
204	No Content	Webhook subscriber deleted successfully.	None
404	Not Found	Resource not found.	ErrorResponse
500	Internal Server Error	Internal server error.	ErrorResponse

List recent deliveries for a webhook subscriber¶

GET /webhook-subscribers/{subscriberId}/deliveries

Code samples

curl -X GET https://localhost:9543/api/v0.9/webhook-subscribers/{subscriberId}/deliveries \
  -u {username}:{password} \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'

Returns the most recent webhook delivery attempts for a single subscriber, newest first.

Authentication¶

Parameters

Name	In	Type	Required	Description
subscriberId	path	string	true	The webhook subscriber's handle (its `id` in request/response payloads), not the internal database uuid.

Example responses

200 Response

{
  "list": [
    {
      "deliveryId": "del-abc123",
      "eventType": "apikey.generated",
      "occurredAt": "2019-08-24T14:15:22Z",
      "status": "DELIVERED",
      "lastHttpStatus": 200,
      "lastError": "string",
      "lastAttemptAt": "2019-08-24T14:15:22Z",
      "deliveredAt": "2019-08-24T14:15:22Z"
    }
  ]
}

404 Response

{
  "status": "error",
  "code": "ORG_NOT_FOUND",
  "message": "Organization not found."
}

500 Response

{
  "status": "error",
  "code": "INTERNAL_SERVER_ERROR",
  "message": "An unexpected error occurred."
}

Responses

Status	Meaning	Description	Schema
200	OK	Recent delivery attempts for this webhook subscriber.	Inline
404	Not Found	Resource not found.	ErrorResponse
500	Internal Server Error	Internal server error.	ErrorResponse

Response Schema

Status Code 200

Name	Type	Required	Restrictions	Description
» list	[WebhookSubscriberDeliverySummary]	false	none	[A single delivery attempt made to a webhook subscriber.]
»» deliveryId	string	false	none	none
»» eventType	string¦null	false	none	none
»» occurredAt	string(date-time)¦null	false	none	none
»» status	string	false	none	none
»» lastHttpStatus	integer¦null	false	none	none
»» lastError	string¦null	false	none	none
»» lastAttemptAt	string(date-time)¦null	false	none	none
»» deliveredAt	string(date-time)¦null	false	none	none

Enumerated Values

Property	Value
status	PENDING
status	IN_FLIGHT
status	DELIVERED
status	FAILED