# Subscribe to a webhook

`POST /v2/webhooks`

**Base URLs:**

- Sandbox: `https://api.sandbox.bobgo.co.za`
- Production: `https://api.bobgo.co.za`

**Authentication:** Bearer token required (see the Authentication page).

## Example request

```bash
curl -X POST 'https://api.sandbox.bobgo.co.za/v2/webhooks' \
  -H "content-type: application/json" \
  -H "Authorization: Bearer <API_KEY>" \
  -d '{
  "webhook_subscriptions": [
    {
      "delivery_url": "https://somewebhookurl.com",
      "topic": "fulfillment/created",
      "status": "active"
    }
  ]
}'
```

Creates subscriptions, or changes existing ones. Send them as an array in
`webhook_subscriptions`, even when there is only one.

| Field | Type | Required | Notes |
| --- | --- | --- | --- |
| `webhook_subscriptions` | array | yes | The subscriptions to create or change. |
| `webhook_subscriptions[].topic` | string | yes | One of the [topics](README.md#topics). |
| `webhook_subscriptions[].delivery_url` | string | yes | Where to send the events. Use `https://`: Bob Go accepts any URL with a scheme and a host, but the payloads carry customer details. |
| `webhook_subscriptions[].status` | string | yes | `active` or `inactive`. |
| `webhook_subscriptions[].id` | integer | no | An existing subscription to change instead of creating a new one. `topic`, `delivery_url` and `status` are still required. An `id` that does not exist creates a new subscription. |

One topic can have several delivery URLs. Within one request the same URL
cannot be subscribed to the same topic twice, but nothing stops a second
request from adding it again, and each copy gets its own deliveries. List your
subscriptions before adding one.

To switch a subscription back on after failures deactivated it, send its `id`
with `status: "active"`. That also clears `first_failed_time`.

## Response

**Every subscription on the account**, as a bare array ordered by topic, not
only the ones you sent:

```json
[
  {
    "id": 364,
    "account_id": 1234,
    "topic": "fulfillment/created",
    "delivery_url": "https://somewebhookurl.com",
    "status": "active",
    "first_failed_time": null,
    "time_created": "2026-09-05T08:30:00Z",
    "time_modified": "2026-09-05T08:30:00Z"
  }
]
```