Managing Subscriptions

You can manage your own webhook subscriptions directly through the API — no support request required. These endpoints let you discover the events available to you, subscribe to a set of events, and update an existing subscription. Your current subscriptions are returned by GET {baseUrl}/auth/me.

Sample Response

{
	"data": {
		"user": {
			"partner_id": 449,
			"name": "Some Partner",
			"email": "[email protected]",
			"key": "Some Partner",
			"status": 1
		},
		"webhook_subscriptions": [
			{
				"id": 6,
				"subscribed_events": [
					"order_status_changed"
				],
				"url": "https://[domain where the webhook is]/ef2d74db-073f-4356-8eae-da6a4915bca3",
				"is_active": true,
				"retries": 3,
				"last_request_at": "2026-07-02 16:11:45",
				"created_at": "2026-06-29 09:42:51"
			}
		]
	},
	"success": true
}

All endpoints below are authenticated with your partner Bearer token (the same token used

One subscription per partner

A partner may hold only one subscription. Attempting to create a second one returns 422 — update the existing subscription instead.

List Available Events

Returns the events you are allowed to subscribe to. Use these values in subscribed_events when creating or updating a subscription.

GET {baseUrl}/webhooks

Response — 200 OK

{
  "success": true,
  "data": {
    "events": ["order_status_changed"]
  }
}

List Your Subscriptions

Your subscriptions are returned in the webhook_subscriptions array of your profile. The signing secret is never included in this response.

GET {baseUrl}/auth/me

Response — 200 OK

{
  "success": true,
  "data": {
    "user": {
      "partner_id": 4,
      "name": "Test Partner",
      "email": "[email protected]",
      "key": "test-partner-key",
      "status": 1
    },
    "webhook_subscriptions": [
      {
        "id": 12,
        "subscribed_events": ["order_status_changed"],
        "url": "https://partner.example.com/webhooks/swyft",
        "is_active": true,
        "retries": 3,
        "last_request_at": null,
        "created_at": "2026-06-29 12:00:00"
      }
    ]
  }
}

Create a Subscription

Subscribe to one or more events.

POST {baseUrl}/webhooks

Request body

Field	Required	Default	Description
url	Yes	—	HTTPS endpoint the payloads are delivered to.
subscribed_events	Yes	—	Non-empty list of events to receive. Each value must be one returned by List Available Events.
token	No	null	Optional bearer token sent in the Authorization header of each delivery.
retries	No	3	Number of delivery retries for failed requests (0–5).
is_active	No	true	Whether the subscription is active.

{
  "url": "https://partner.example.com/webhooks/swyft",
  "subscribed_events": ["order_status_changed"]
}

Response — 201 Created

The secret_key is returned exactly once, here on creation. Store it now — it is used to verify the X-Webhook-Signature header (see Signature Validation) and cannot be retrieved again.

{
  "success": true,
  "data": {
    "id": 12,
    "subscribed_events": ["order_status_changed"],
    "url": "https://partner.example.com/webhooks/swyft",
    "is_active": true,
    "retries": 3,
    "last_request_at": null,
    "created_at": "2026-06-29 12:00:00",
    "secret_key": "whsec_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
  }
}

Duplicate — 422 Unprocessable Content

If you already have a subscription, the existing subscription id is returned; use Update a Subscription instead.

{
  "success": false,
  "message": "A subscription already exists. Use PATCH {baseUrl}/webhooks/{id} to update it.",
  "errors": { "webhook_subscription_id": 12 }
}

Update a Subscription

Partially update your subscription. Only the fields you send are changed. The signing secret is preserved and is never returned.

PATCH {baseUrl}/webhooks/{id}

Request body — all fields optional: url, subscribed_events, token, retries, is_active. Any subscribed_events you send must be values returned by List Available Events.

{
  "is_active": false
}

Response — 200 OK

{
  "success": true,
  "data": {
    "id": 12,
    "subscribed_events": ["order_status_changed"],
    "url": "https://partner.example.com/webhooks/swyft",
    "is_active": false,
    "retries": 3,
    "last_request_at": null,
    "created_at": "2026-06-29 12:00:00"
  }
}

Pause vs. unsubscribe

To temporarily stop deliveries, set is_active: false with the update endpoint above — the subscription (and its signing secret) is kept and can be re-enabled later. To permanently remove the subscription, use Unsubscribe below.

Unsubscribe

Remove one of your own subscriptions. Deliveries stop immediately and the subscription no longer appears in your account. This is not reversible through the API — to resume, create a new subscription with Create a Subscription (which issues a fresh signing secret).

DELETE {baseUrl}/webhooks/{id}

Response — 200 OK

{
  "success": true,
  "data": {
    "message": "Webhook subscription deleted."
  }
}