Comidoc Developer API documentation

Receive new coupons without polling

API Pro accounts can follow courses without a watch-count limit. Configure one public HTTPS destination in your developer account’s Webhook tab, copy the signing secret, and send a free test. Then create watches using your API key. Watches belong to your account and survive key rotation.

Keys created before watches were introduced retain their existing scopes. Create a new key with watches:read and watches:write to use these endpoints. New portal keys include both scopes.

1. Follow a course

curl -X POST 'https://comidoc.com/api/v1/watches' \
  -H 'Authorization: Bearer cmd_live_your_key' \
  -H 'Content-Type: application/json' \
  --data '{"course_id":3836244}'

{
  "data": {
    "id": "watch_example",
    "course_id": 3836244,
    "course_title": "Python Automation",
    "course_slug": "python-automation",
    "created_at": "2026-10-03T12:00:00Z"
  },
  "meta": { "...": "standard API metadata and shared quota" }
}

A new watch returns 201; creating the same active watch again returns 200 with the existing identifier. Existing coupons are not replayed. Only newly confirmed free coupons after registration are eligible; repeated verification of the same coupon does not produce additional notifications. Reactivation of the same coupon is not sent again to the same destination. Practice tests and inactive or opted-out courses are excluded. Notifications continue until you delete the watch.

2. Receive a notification

{
  "id": "cf840882-07ec-4830-8e22-834a67d9a03b",
  "type": "coupon.available",
  "created_at": "2026-10-03T12:05:00Z",
  "test": false,
  "watch_id": "watch_example",
  "data": {
    "course": { "id": 3836244, "title": "Python Automation", "url": "https://comidoc.com/udemy/python-automation" },
    "offer": {
      "id": "offer_example",
      "coupon_code": "KEEPLEARNING",
      "udemy_url": "https://www.udemy.com/course/python-automation/?couponCode=KEEPLEARNING",
      "expires_at": "2026-10-05T12:00:00Z",
      "last_confirmed_active_at": "2026-10-03T12:04:58Z",
      "remaining_uses": 80
    }
  }
}

Tests use type: "webhook.test", test: true, and data.message instead of an offer. The offer can become unavailable after confirmation; notification does not reserve a redemption. Unavailable offers are discarded before retrying. Delivery order is not guaranteed.

3. Verify and acknowledge

Verify the signature against the exact raw request body before parsing JSON. The signing secret is separate from your API key. Headers are webhook-id, webhook-timestamp (Unix seconds), and webhook-signature. The HMAC-SHA256 input is id.timestamp.rawBody; the key is the Base64-decoded signing secret after removing whsec_.

import { createHmac, timingSafeEqual } from 'node:crypto';

function verifyWebhook(rawBody, headers, secret) {
  const id = headers['webhook-id'];
  const timestamp = headers['webhook-timestamp'];
  const signature = headers['webhook-signature'];
  if (typeof id !== 'string' || typeof timestamp !== 'string' ||
      typeof signature !== 'string' || !/^\d+$/.test(timestamp)) return false;
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false;
  const expected = createHmac('sha256', Buffer.from(secret.slice(6), 'base64'))
    .update(id + '.' + timestamp + '.' + rawBody).digest();
  return signature.split(' ').some(entry => {
    if (!entry.startsWith('v1,')) return false;
    const received = Buffer.from(entry.slice(3), 'base64');
    return received.length === expected.length && timingSafeEqual(received, expected);
  });
}

Persist the webhook-id and enqueue your work atomically, then respond with 2xx promptly. Return 2xx for already accepted identifiers. Retain deduplication records beyond the retry window; timestamps alone do not prevent duplicate processing. Automatic retries reuse the same ID and body with a fresh timestamp and signature.

Shared credits and delivery failures

Creating or listing watches costs one API credit per call. One coupon notification accepted with 2xx costs one shared credit, regardless of retries. Tests and permanently failed deliveries cost zero. A credit is temporarily reserved before sending; it becomes charged after 2xx or is released after final failure or cancellation. The portal separates API, webhook, reserved, and available credits. API response quota fields include reservations so clients cannot spend held credits twice.

The optional webhook credit limit is a UTC calendar-month ceiling within the shared quota, not an additional allowance. Zero pauses new coupon deliveries; tests remain available. The monthly counter is stored in PostgreSQL and survives application and Redis restarts.

Normal delivery attempts are immediate, then approximately 1 minute, 5 minutes, 15 minutes, 1 hour, and 3 hours after the previous failure. Redirects are not followed. HTTP 410 ends the delivery immediately. Other non-2xx responses and connection failures are retried. An ambiguous acknowledgement after a crash may cause a duplicate delivery: use the stable ID to deduplicate.

Quota or webhook-limit exhaustion pauses new deliveries. They resume automatically once credits are available or the limit is raised, provided the offer remains eligible. Expired Pro access stops deliveries but retains watches; there is no replay of coupons missed during that period. Changing the URL or replacing the signing secret cancels queued messages for the old configuration. A request already in flight may complete. View recent results in the portal and refresh to check worker progress.

List or stop watches

curl 'https://comidoc.com/api/v1/watches' \
  -H 'Authorization: Bearer cmd_live_your_key'

curl -X DELETE 'https://comidoc.com/api/v1/watches/watch_example' \
  -H 'Authorization: Bearer cmd_live_your_key'

Deletion is free and remains available after quota or Pro expiry. It returns {"deleted":true,"meta":{…}}. Stop watches through REST; this feature does not create an MCP notification subscription. Categories, topics, and instructors are outside this first version.

Listing watches is paginated. Send GET /api/v1/watches?limit=100, then pass pagination.next_cursor as cursor until it is null. The response also includes pagination.total and pagination.limit. Page size follows your account’s maximum; each page costs one API credit. Avoid modifying watches while iterating pages.