Hooks
External service hooks for subscription management
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 explicitlyFalseFields set to
Trueare ignored (no change to user)Skips users not found in database (no error raised)
Side Effects:
Updates user's
email_allowed,sms_allowed, and/orcall_allowedfields for matched usersUses 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_usersarray
Error Responses:
400: "Hash mismatch error" - Invalid hash_value or gateway not configured400: "Time gap error" - request_datetime more than 1 minute old400: "Ensure unsubscribed_users field has at most 100 items." - Array too large
Maximum 100 users per request. Throttling scope: user-unsubscribe.
Identifier for the calling service. Must match a configured subscription gateway
in ACTIVE_SUBSCRIPTION_GATEWAYS or SUBSCRIPTION_GATEWAY dynamic settings.
HMAC hash for request validation. Generated by the subscription gateway's
get_unsubscription_hash(request_datetime) method. Algorithm depends on gateway implementation.
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).
Unsubscription processed successfully. Users' communication preferences updated. Returns empty response body with 200 status.
No content
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.
Too many requests (throttled)
No content
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-unsubscribeCreates 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_MAPsetting (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
emailORphone(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 explicitlyFalseFields set to
Trueare ignored (no change to user)Skips users not found in database (no error raised)
If no
Falsevalues in permission fields, skips user (no update or audit event)
Side Effects:
Updates user's
email_allowed,sms_allowed, and/orcall_allowedfields for matched usersCreates 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_usersarray
Error Responses:
400: "Hash mismatch error" - Invalid hash_value, missing secret key, or KVKK_UNSUBSCRIPTION_SECRET_MAP not configured400: "Time gap error" - request_datetime more than 1 minute old400: "Only email or phone field acceptable" - Both email and phone provided400: "User data must include email or phone field" - Neither email nor phone provided400: "Ensure unsubscribed_users field has at most 100 items." - Array too large
Maximum 100 users per request. Throttling scope: user-unsubscribe.
Identifier for the calling service. Must have a corresponding secret key
in KVKK_UNSUBSCRIPTION_SECRET_MAP setting.
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 timestamp in ISO format. Must be within 1 minute of server time (time gap validated as: (now - request_datetime).seconds / 60 < 1).
Unsubscription processed successfully. Users' communication preferences updated. Audit events created for each user update. Returns empty response body with 200 status.
No content
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.
Too many requests (throttled)
No content
Last updated
Was this helpful?