Hooks

External service hooks for subscription management

Bulk unsubscribe users (external service hook)

patch

External service hook for bulk unsubscribing users from communication channels. Requires HMAC hash validation for security.

Security:

• Public endpoint secured via hash validation

• Throttled with scope user-unsubscribe

Hash Validation: Hash is calculated via subscription gateway's hash generation method. The gateway is retrieved from dynamic settings (ACTIVE_SUBSCRIPTION_GATEWAYS or SUBSCRIPTION_GATEWAY). If gateway doesn't implement hash generation, validation fails.

User Matching Logic:

• Users identified by email match against primary email OR verified email addresses

• Only sets permission fields (email_allowed, sms_allowed, call_allowed) that are explicitly False

• Fields set to True are ignored (no change to user)

• Skips users not found in database (no error raised)

Side Effects:

• Updates user's email_allowed, sms_allowed, and/or call_allowed fields for matched users

• Uses database transaction to ensure all-or-nothing updates

Validation:

• Request datetime must be within 1 minute of server time (60 seconds)

• Maximum 100 users per request

• Hash must match calculated hash from subscription gateway

• At least one user required in unsubscribed_users array

Error Responses:

• 400: "Hash mismatch error" - Invalid hash_value or gateway not configured

• 400: "Time gap error" - request_datetime more than 1 minute old

• 400: "Ensure unsubscribed_users field has at most 100 items." - Array too large

Maximum 100 users per request. Throttling scope: user-unsubscribe.

Body

application/json

service_namestring · max: 20Required

Identifier for the calling service. Must match a configured subscription gateway in ACTIVE_SUBSCRIPTION_GATEWAYS or SUBSCRIPTION_GATEWAY dynamic settings.

hash_valuestringRequired

HMAC hash for request validation. Generated by the subscription gateway's get_unsubscription_hash(request_datetime) method. Algorithm depends on gateway implementation.

request_datetimestring · date-timeRequired

Request timestamp in ISO format. Must be within 1 minute of server time to be valid (time gap validated as: (now - request_datetime).seconds / 60 < 1).

Responses

200

Unsubscription processed successfully. Users' communication preferences updated. Returns empty response body with 200 status.

No content

400

Validation error, hash mismatch, or time gap error.

Common errors:

• Hash mismatch error
• Time gap error
• Ensure unsubscribed_users field has at most 100 items.

application/json

429

Too many requests (throttled)

patch

/users/hooks/unsubscribe-user/

HTTPcURLJavaScriptPython

PATCH /users/hooks/unsubscribe-user/ HTTP/1.1
Host: sandbox.akinon.com
Content-Type: application/json
Accept: */*
Content-Length: 199

{
  "service_name": "text",
  "hash_value": "text",
  "request_datetime": "2026-03-07T02:17:25.640Z",
  "unsubscribed_users": [
    {
      "email": "[email protected]",
      "email_allowed": true,
      "sms_allowed": true,
      "call_allowed": true
    }
  ]
}

No content

KVKK-compliant bulk unsubscription

patch

External service hook for KVKK (Turkish Personal Data Protection Law) compliant bulk unsubscription. Uses KVKK-specific hash validation with SHA-256 algorithm.

Security:

• Public endpoint secured via SHA-256 hash validation

• Throttled with scope user-unsubscribe

• Creates audit events for compliance tracking

Hash Validation:

• Hash algorithm: SHA-256

• Hash input: {secret_key}{request_datetime.isoformat()}

• Secret keys configured via KVKK_UNSUBSCRIPTION_SECRET_MAP setting (dict mapping service_name to secret)

• If setting not configured or service_name not in map, validation fails

User Identification:

• Users can be identified by email OR phone (mutually exclusive, not both)

• Email matching: against primary email OR verified email addresses

• Phone matching: against user's phone number

• If neither email nor phone provided, validation error

• If both email and phone provided, validation error

User Matching Logic:

• Only sets permission fields (email_allowed, sms_allowed, call_allowed) that are explicitly False

• Fields set to True are ignored (no change to user)

• Skips users not found in database (no error raised)

• If no False values in permission fields, skips user (no update or audit event)

Side Effects:

• Updates user's email_allowed, sms_allowed, and/or call_allowed fields for matched users

• Creates audit event for each updated user for KVKK compliance

• Audit event includes: service_name and all permission flags from request

• Uses database transaction to ensure all-or-nothing updates

Validation:

• Request datetime must be within 1 minute of server time (60 seconds)

• Maximum 100 users per request

• Hash must match SHA-256 hash: sha256(secret_key + request_datetime.isoformat()).hexdigest()

• Each user must have exactly one of: email or phone

• At least one user required in unsubscribed_users array

Error Responses:

• 400: "Hash mismatch error" - Invalid hash_value, missing secret key, or KVKK_UNSUBSCRIPTION_SECRET_MAP not configured

• 400: "Time gap error" - request_datetime more than 1 minute old

• 400: "Only email or phone field acceptable" - Both email and phone provided

• 400: "User data must include email or phone field" - Neither email nor phone provided

• 400: "Ensure unsubscribed_users field has at most 100 items." - Array too large

Maximum 100 users per request. Throttling scope: user-unsubscribe.

Body

application/json

service_namestring · max: 20Required

Identifier for the calling service. Must have a corresponding secret key in KVKK_UNSUBSCRIPTION_SECRET_MAP setting.

hash_valuestringRequired

KVKK-specific SHA-256 hash for request validation. Calculated as: sha256(secret_key + request_datetime.isoformat()).hexdigest() where secret_key is retrieved from KVKK_UNSUBSCRIPTION_SECRET_MAP[service_name].

request_datetimestring · date-timeRequired

Request timestamp in ISO format. Must be within 1 minute of server time (time gap validated as: (now - request_datetime).seconds / 60 < 1).

Responses

200

Unsubscription processed successfully. Users' communication preferences updated. Audit events created for each user update. Returns empty response body with 200 status.

No content

400

Validation error, hash mismatch, or time gap error.

Common errors:

• Hash mismatch error
• Time gap error
• Only email or phone field acceptable
• User data must include email or phone field
• Ensure unsubscribed_users field has at most 100 items.

application/json

429

Too many requests (throttled)

patch

/users/hooks/kvkk-unsubscribe-user/

HTTPcURLJavaScriptPython

PATCH /users/hooks/kvkk-unsubscribe-user/ HTTP/1.1
Host: sandbox.akinon.com
Content-Type: application/json
Accept: */*
Content-Length: 214

{
  "service_name": "text",
  "hash_value": "text",
  "request_datetime": "2026-03-07T02:17:25.640Z",
  "unsubscribed_users": [
    {
      "phone": "text",
      "email": "[email protected]",
      "email_allowed": true,
      "sms_allowed": true,
      "call_allowed": true
    }
  ]
}

No content