Receive message
Describes how to receive messages depending on the subscription type provided by Pub/Sub.
If subscription type is Pull
If the subscription type is created as Pull in the Pub/Sub service, users can receive messages through the subscription and send acknowledgment responses.
For details on how to create a subscription, refer to Create subscription.
To request messages via API, you must obtain an Access Key ID and Secret Access Key from KakaoCloud Console > Profile (top right) > Credentials > IAM Access Key.
Key concepts
| Key concept | Description |
|---|---|
| Subscription type | Pull: User requests message delivery |
| Acknowledgment wait time | Time to wait for message acknowledgment |
| Acknowledgment | If not acknowledged within wait time, message will be re-delivered |
Receive message
If the subscription type is Pull, you can receive messages via the console or API.
Messages published to a topic can be viewed through the console's receive test feature.
To perform a receive test, you must first publish a message to the topic.
For more details, refer to Publish message.
-
Go to KakaoCloud Console > Analytics > Pub/Sub.
-
In the Topic menu, select the topic that contains the subscription to test.
-
In the Message tab, configure the receive test options, then click [Get message].
Field Description Select subscription Subscription selector box Number of messages Number of messages to retrieve Message content Contents of the published message body; if none, shown as -Publish time Time the message was published Attributes Attributes of the published message; click view to see key-value pairs Max delivery attempts Number of times the message was retried Acknowledged Acknowledgment status based on wait time -
In the receive test list, click Message content or View attributes to check message details.
You can also perform message retrieval from the Message tab in the subscription detail page.
If subscription type is Push
If the subscription type is set to Push, messages are received as follows:
Key concepts
| Key concept | Description |
|---|---|
| Subscription type | Push: Pub/Sub sends messages to user-defined endpoint |
| Endpoint URL | Endpoint server URL to receive published messages |
| Message delivery format | Messages are received according to the delivery format set in the subscription - Default delivery: Sent in JSON format containing both message data and metadata - Unwrapped payload: Only the decoded message data is sent in the body; metadata inclusion can be configured additionally ㄴ Include metadata: Can be configured when the unwrapped payload option is selected |
| Acknowledgment wait time | Time to wait for HTTP response from the endpoint |
| Acknowledgment | If no HTTP response is received within the wait time, the message is resent |
When using a Push subscription, message push is only available to endpoints using KakaoCloud public IP.
Configure security group
When using a Push subscription type, you must configure the security group to allow message delivery to the endpoint server.
You need to configure an inbound rule on the security group associated with the resource linked to the endpoint URL.
Although setting the source range to Any allows push delivery, it is recommended to specify the source IP for security purposes.
For security reasons, the following ports cannot be used as Push endpoints: 22, 1433, 1521, 3306, 3389, 6379, 27017
Source IP ranges for Push subscription security group settings:
Source IP: 61.109.238.137, 61.109.238.107, 61.109.237.249, 61.109.238.114, 61.109.238.74, 61.109.236.65
For details on security groups, refer to Create and manage security group.
- Go to KakaoCloud Console > Beyond Networking Service > VPC.
- Click the Security group menu, then select the group where inbound rules will be configured.
- Be sure to select the group associated with the endpoint resource.
- In the Inbound rules tab, click [Manage inbound rules], then configure the necessary rules.
Receive message
When a message is published to a topic, it is received at the configured endpoint in the format shown below.
To receive messages at a Push endpoint, your server must handle POST requests sent by Pub/Sub.
Message data is received according to the subscription's message delivery format.
Example: Message publish request
{
"subscription": "string",
"messages": [
{
"message": {
"data": "string",
"attributes": {
"key": ["value"]
},
"messageId": "string",
"publishTime": "time (RFC3339)"
}
}
]
}
Example: Message reception
Published messages can be received in the following three formats:
1. Default delivery
Content-Type: application/json
User-Agent: KakaoCloud PubSub
"subscription": string
"messages": [
{
"message": {
"data": "7ISc7Jq47Yq567OEIOuPmeygle2Vmeq1rA=",
"attributes": {
"key1": "value1",
"key2": "value2"
},
"messageId": "952050975384541999942480274511084280181747364976",
"publishTime": "2025-05-16T03:09:36Z"
}
}
]
2. Unwrapped payload (metadata excluded)
Message receive test
3. Unwrapped payload (metadata included)
kakaoc-Message-Id: 952050975384541999942480274511084280181747364976
kakaoc-Subscription-Name: push-test
kakaoc-Publish-Time: 2025-05-16T03:09:36Z
key1: value1
key2: value2
Message receive test
If subscription type is Object Storage
If the subscription type is created as Object Storage in the Pub/Sub service, users can send messages to an Object Storage bucket via the subscription.
An Object Storage bucket must be created in advance, and the Pub/Sub service agent must have write permission on the bucket.
The service agent is created automatically when the Pub/Sub service starts. For details, refer to Service agent account.
Key concepts
| Item | Description |
|---|---|
| Bucket | Object Storage bucket where messages are stored ⚠️ You must pre-create the bucket and grant write permission to the Pub/Sub service agent |
| File format | Format of the output file stored in the bucket {bucket-name}/{YYYY/MM/DD/HH}/{UUID} - {YYYY/MM/DD/HH} : Message publish timestamp (UTC) Example 2024/11/19/04/UUID |
| File prefix (optional) | Adds prefix to all output files {bucket-name}/{prefix-path}/{YYYY/MM/DD/HH}/{prefix}{UUID} Examples - Filename only: pubsub_ 2024/11/19/04/pubsub_UUID - Path + filename: pubsub/message_data/test_ pubsub/message_data/2024/11/19/04/test_UUID |
| File suffix (optional) | Adds suffix to all output files {bucket-name}/{YYYY/MM/DD/HH}/{UUID}{suffix} Examples - Filename only: _pubsub 2024/11/19/04/UUID_pubsub - Filename + extension: _pubsub.log 2024/11/19/04/UUID_pubsub.log |
| Max batch duration | Time interval for storing files to the bucket |
| Export channel count | Number of channels for exporting messages to Object Storage |
Receive message
Message content (data) published in Base64 is decoded upon receipt.
Messages are uploaded to the bucket in multipart format.
Due to errors or cancellations, incomplete multipart uploads may be stored and not visible in the console.
It is recommended to configure a lifecycle rule to permanently delete incomplete uploads.
Example: Object Storage file upload
Object Storage file upload example
For Object Storage subscription types, you must include message content (data) when publishing a message.
Only the message content is stored in the file; message attributes are not saved.
Export channel
When an Object Storage subscription is created, an export channel to the bucket is automatically activated.
(*Activation/deactivation of the export channel is currently only supported via the console.)
Export deactivation policy
If the export channel is deactivated, transmission to Object Storage stops.
However, unprocessed messages at the time of deactivation may still be sent via multipart upload.
If issues such as bucket permission errors or non-existent buckets occur, the export channel is automatically deactivated.
Follow the steps below and re-execute [Start export].
- If the Object Storage subscription status changes to InvalidBucket or Unauthorized:
- InvalidBucket: Create a new bucket and update the subscription with the new bucket info.
- Unauthorized: Either switch to a new bucket or update permissions on the existing bucket.
- Go to the subscription detail page and click [Start export] to re-enable the channel.
- Verify that the subscription status has changed back to Active.