Help Center

Integrations (API Keys & Webhooks)

Connect MyDojang to your own scripts, automations, or third-party tools like Zapier. Use the read-only REST API to pull student and attendance data, and webhooks to receive real-time event notifications when things happen in your studio. This feature is available on plans that include API access and must be enabled by a platform admin for your studio.

API Keys
  1. 1

    Create an API key

    Go to Settings > Integrations and click the API Keys tab. Click New Key, give it a descriptive name (e.g. "Zapier Integration" or "My Script"), then click Create Key.

  2. 2

    Copy your key immediately

    The full API key is shown only once right after creation. Copy it and store it somewhere safe — for security, MyDojang does not store the raw key and cannot show it again.

  3. 3

    Use the key in your requests

    Include the key in the Authorization header of every API request: Authorization: Bearer mdk_<your-key>. All v1 API endpoints require this header.

  4. 4

    Revoke a key

    To revoke access, click the trash icon next to any key in the API Keys list. Revoked keys stop working immediately. Create a new key if you need to replace one.

REST API Endpoints
  1. 1

    Available endpoints

    The following read-only endpoints are available under the base path /api/v1/. All responses are JSON. Endpoints are paginated where noted.

  2. 2

    GET /api/v1/students

    List active students. Supports filtering by name and beltRankId. Returns paginated results with student profile data.

  3. 3

    GET /api/v1/attendance

    List attendance records. Filter by studentId, startDate, and endDate to narrow results.

  4. 4

    GET /api/v1/classes

    List class instances. Filter by status (SCHEDULED, COMPLETED, CANCELLED), date range, and locationId.

  5. 5

    GET /api/v1/belt-tests

    List belt test events with their registrations. Filter by status and date range.

Webhooks
  1. 1

    Add a webhook endpoint

    Go to Settings > Integrations and click the Webhooks tab. Click Add Endpoint, enter your HTTPS URL, and select the events you want to receive. Click Add Endpoint to save.

  2. 2

    Copy your signing secret

    After adding an endpoint, a signing secret is shown once. Copy it now — you will use it to verify that incoming requests are genuinely from MyDojang.

  3. 3

    Available event types

    student.created, student.updated, student.archived, attendance.checked_in, belt_test.scheduled, belt_test.result_recorded, billing.payment_received, billing.payment_failed, message.sent

  4. 4

    Enable or disable an endpoint

    Use the toggle switch next to each endpoint to temporarily pause delivery without deleting the endpoint. Re-enable it when you are ready to receive events again.

  5. 5

    View delivery history

    Click Deliveries next to any endpoint to see the last 50 delivery attempts, their status (DELIVERED / FAILED), and any error message. You can click Resend to manually retry a failed delivery.

Verifying Webhook Signatures
  1. 1

    Why verify signatures?

    Every webhook request from MyDojang includes an X-MyDojang-Signature header containing a sha256= HMAC signature of the raw request body. Verifying this signature ensures the request genuinely came from MyDojang and was not tampered with.

  2. 2

    Verification example (Node.js)

    Use the following code to verify the signature. Compare using timingSafeEqual to prevent timing attacks. The secret is the signing secret shown when you created the endpoint.

  3. 3

    Read the raw body

    Important: compute the HMAC over the raw request body bytes before any JSON parsing. Parsing the body first can change whitespace and invalidate the signature.

Signature verification (Node.js)

const crypto = require('crypto');

function verifySignature(secret, body, signature) {
  const expected =
    'sha256=' +
    crypto.createHmac('sha256', secret).update(body).digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(signature)
  );
}

// In your webhook handler:
// const body = req.rawBody;          // raw bytes / string
// const sig  = req.headers['x-mydojang-signature'];
// if (!verifySignature(SECRET, body, sig)) {
//   return res.status(403).send('Invalid signature');
// }
Troubleshooting
  1. 1

    403 API access not enabled

    API access is a plan feature that also requires a platform admin to enable it for your studio. Contact support if you believe your plan includes API access but you are receiving a 403 error.

  2. 2

    401 Unauthorized

    Check that your Authorization header is formatted correctly: Authorization: Bearer mdk_<key>. Ensure the key has not been revoked. Create a new key if needed.

  3. 3

    Webhook delivery failures

    Your endpoint must return a 2xx HTTP status code within the request timeout. If it times out or returns a non-2xx response, the delivery is marked FAILED and retried automatically up to 4 times (after 5 min, 30 min, 2 h, and 8 h). Check the Deliveries panel for error details.

  4. 4

    Signature mismatch

    Make sure you are computing the HMAC over the raw request body before parsing it. Ensure you are using the correct signing secret — each endpoint has its own unique secret.

MyDojang