MSDN Documentation

Webhooks API Reference

The Webhooks API allows you to receive real-time notifications about events happening within your application. By subscribing to specific events, you can trigger actions in your own systems without the need for constant polling. This is an essential tool for building integrated and responsive applications.

Authentication

All requests to the Webhooks API must be authenticated. Authentication is performed using an API key, which should be included in the Authorization header as a Bearer token. 

Authorization: Bearer YOUR_API_KEY

Obtain your API key from your account settings.

API Endpoints

GET /webhooks

Retrieves a list of all active webhook subscriptions for your account.

Query Parameters:
Name Type Description Required
status string Filter by webhook status. Possible values: active, inactive. No
event_type string Filter by the type of event subscribed to. No
Example Request:
curl -X GET \
  https://api.msdn.example.com/v1/webhooks \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json'
Example Response:
[
  {
    "id": "whk_abc123",
    "url": "https://your.domain.com/webhook-receiver",
    "event_types": ["user.created", "order.placed"],
    "status": "active",
    "created_at": "2023-10-27T10:00:00Z",
    "updated_at": "2023-10-27T10:00:00Z"
  },
  {
    "id": "whk_def456",
    "url": "https://another.domain.com/listener",
    "event_types": ["product.updated"],
    "status": "active",
    "created_at": "2023-10-26T15:30:00Z",
    "updated_at": "2023-10-26T15:30:00Z"
  }
]

POST /webhooks

Creates a new webhook subscription.

Request Body:
Name Type Description Required
url string The URL where the webhook events will be delivered. Must be HTTPS. Yes
event_types array of string A list of event types to subscribe to. Yes
secret string An optional secret token to use for signing webhook requests. No
Example Request:
curl -X POST \
  https://api.msdn.example.com/v1/webhooks \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "url": "https://your.domain.com/new-webhook-handler",
    "event_types": ["user.deleted", "payment.received"],
    "secret": "my-super-secret-key"
  }'
Example Response (201 Created):
{
  "id": "whk_ghi789",
  "url": "https://your.domain.com/new-webhook-handler",
  "event_types": ["user.deleted", "payment.received"],
  "status": "active",
  "created_at": "2023-10-27T11:00:00Z",
  "updated_at": "2023-10-27T11:00:00Z"
}

GET /webhooks/{id}

Retrieves a specific webhook subscription by its ID.

Path Parameters:
Name Type Description
id string The unique identifier of the webhook.
Example Request:
curl -X GET \
  https://api.msdn.example.com/v1/webhooks/whk_abc123 \
  -H 'Authorization: Bearer YOUR_API_KEY'
Example Response:
{
  "id": "whk_abc123",
  "url": "https://your.domain.com/webhook-receiver",
  "event_types": ["user.created", "order.placed"],
  "status": "active",
  "created_at": "2023-10-27T10:00:00Z",
  "updated_at": "2023-10-27T10:00:00Z"
}

PUT /webhooks/{id}

Updates an existing webhook subscription.

Path Parameters:
Name Type Description
id string The unique identifier of the webhook to update.
Request Body:

You can update any of the fields from the POST request body. Include only the fields you wish to change.

Name Type Description Required
url string The new URL for webhook deliveries. No
event_types array of string The new list of event types to subscribe to. No
status string The new status of the webhook. Possible values: active, inactive. No
Example Request:
curl -X PUT \
  https://api.msdn.example.com/v1/webhooks/whk_abc123 \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "event_types": ["user.created", "order.placed", "product.added"],
    "status": "inactive"
  }'
Example Response:
{
  "id": "whk_abc123",
  "url": "https://your.domain.com/webhook-receiver",
  "event_types": ["user.created", "order.placed", "product.added"],
  "status": "inactive",
  "created_at": "2023-10-27T10:00:00Z",
  "updated_at": "2023-10-27T11:30:00Z"
}

DELETE /webhooks/{id}

Deletes a webhook subscription.

Path Parameters:
Name Type Description
id string The unique identifier of the webhook to delete.
Example Request:
curl -X DELETE \
  https://api.msdn.example.com/v1/webhooks/whk_abc123 \
  -H 'Authorization: Bearer YOUR_API_KEY'
Example Response (204 No Content):

A successful deletion returns an empty response with a 204 No Content status code.

Supported Events

The following event types are currently supported:

We are continuously expanding our event offerings. Check back for updates or contact us with your suggestions.

Webhook Event Payload

Each webhook event sent to your URL will be a POST request with a JSON payload. The payload structure is consistent across all event types, with specific details varying based on the event.

Generic Payload Structure:

{
  "event": {
    "id": "evt_xyz789",
    "type": "user.created",
    "created_at": "2023-10-27T12:00:00Z",
    "data": {
      // Event-specific data goes here
    }
  },
  "account_id": "acc_12345"
}

The data object contains the specific information related to the event. For example, a user.created event might include:

{
  "id": "usr_abcdef",
  "username": "john_doe",
  "email": "john.doe@example.com",
  "created_at": "2023-10-27T12:00:00Z",
  "status": "pending_verification"
}

Payload Signing and Verification

For security, all incoming webhook requests are signed using an HMAC-SHA256 hash. The signature is provided in the X-MSDN-Signature header.

To verify the integrity of the payload:

  1. Retrieve the webhook's secret key from your dashboard.
  2. Construct a string by concatenating the timestamp (from the X-MSDN-Timestamp header) and the raw request body.
  3. Compute the HMAC-SHA256 hash of this string using your webhook's secret key.
  4. Compare the computed hash with the signature provided in the X-MSDN-Signature header. If they match, the payload is authentic.

Example Headers:

X-MSDN-Signature: t=1678886400,sig=sha256=your_computed_hmac_signature
X-MSDN-Timestamp: 1678886400

Error Handling

Your webhook receiver should respond with an HTTP status code that indicates the outcome of processing the event.

The API will retry failed deliveries (those resulting in 4xx or 5xx status codes) for a period of 24 hours with an exponential backoff strategy.

Rate Limiting

To ensure stability and fair usage, the Webhooks API enforces rate limits. If you exceed the limits, you will receive a 429 Too Many Requests response.

Current limits:

You can find information about your current rate limit status in the response headers: