Receive message

This document explains how to receive messages based on the type of subscription used in the Pub/Sub service.

If subscription type is Pull

When a subscription is created with the type Pull, users can pull and acknowledge messages manually.
For details on creating subscriptions, see Create subscription.

info

To request messages via API, you must issue an access key ID and secret access key from KakaoCloud console > Top-right profile > Certification > IAM access key.

Key concepts

Key concept	Description
Subscription type	Pull: The user explicitly requests message delivery
Ack wait time	Time allowed for acknowledging a received message
Acknowledgement	If no ack is received within the wait time, the message is resent

Receive message

If the subscription type is Pull, you can receive messages via console or API.
Use the console to test message delivery from a topic.

info

To test message reception, you must first publish a message to the topic. See Publish message.

1. Go to KakaoCloud console > Analytics > Pub/Sub.

2. In the Topic menu, select the topic containing the subscription to test.

3. In the Message tab, configure the test settings and click [Fetch messages].

   Field	Description
   Select subscription	Select subscription from dropdown
   Number of messages	Number of messages to fetch
   Message content	Body of the published message; if none, displayed as -
   Published at	Time when the message was published
   Attributes	Click “View attributes” to see key-value pairs
   Retry count	Number of times the message has been retried
   Ack	Acknowledgement status based on ack wait time

4. In the results, click Message content or View attributes to see details of each message.

info

Message fetch can also be performed from the Message tab in the subscription details page.

If subscription type is Push

When using the Push subscription type, messages are sent to a user-defined endpoint.

Key concepts

Key concept	Description
Subscription type	Push: Pub/Sub pushes messages to a specified endpoint
Endpoint URL	Server endpoint to receive published messages
Ack wait time	Time allowed for receiving HTTP response
Acknowledgement	If no HTTP response is received in time, the message is resent

info

With Push subscriptions, message delivery is only supported to endpoint URLs using KakaoCloud public IPs.

Configure security group

Push delivery requires security group settings on the endpoint server.

• The security group attached to the resource serving the endpoint URL must allow inbound access.
• Although allowing “Any” source IP is possible, it is recommended to specify source IPs for security.

caution

For security reasons, the following ports cannot be used as push endpoints: 22, 1433, 1521, 3306, 3389, 6379, 27017

info

Source IPs for push subscription traffic

• Default-Topic: 61.109.235.11
• User topic: 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, see Manage security group.

1. Go to KakaoCloud console > Beyond Networking Service > VPC.
2. In the Security group menu, select the security group for the resource connected to the endpoint.
3. In the Inbound rules tab, click [Manage inbound rules] and add the required rules.

Receive message

When a message is published to a topic, it is sent to the configured endpoint in the following format:

Message delivery format

{
  "subscription": "string",
  "messages": [
    {
      "message": {
        "data": "string",
        "attributes": {
          "key": ["value"]
        },
        "messageId": "string",
        "publishTime": "time (RFC3339)"
      }
    }
  ]
}

If subscription type is Object Storage

If a subscription is created with the type Object Storage, users can deliver messages to an Object Storage bucket through the subscription.

info

An Object Storage bucket must be created in advance, and the Pub/Sub service agent must have write permission for that bucket.
The service agent is created automatically when the Pub/Sub service is first used. For more details, refer to the Service agent account documentation.

Key concepts

Item	Description
Bucket	Target Object Storage bucket for storing messages ⚠️ The bucket must exist beforehand and be granted write permission to the Pub/Sub service agent.
File format	Format of output files saved to the bucket {bucket name}/{YYYY/MM/DD/HH}/{UUID} - {YYYY/MM/DD/HH}: Message publish timestamp - {HH}: UTC time Example output file: 2024/11/19/04/UUID
File prefix (optional)	Adds a prefix to all output files {bucket}/{prefix path}/{YYYY/MM/DD/HH}/{prefix}{UUID} Examples - Filename prefix: pubsub_ → 2024/11/19/04/pubsub_UUID - Path + filename prefix: pubsub/message_data/test_ → pubsub/message_data/2024/11/19/04/test_UUID
File suffix (optional)	Adds a suffix to all output files {bucket}/{YYYY/MM/DD/HH}/{UUID}{suffix} Examples - Filename suffix: _pubsub → 2024/11/19/04/UUID_pubsub - Filename + extension: _pubsub.log → 2024/11/19/04/UUID_pubsub.log
Max batching interval	Time interval for batching files before saving to the bucket
Export channel count	Number of channels used to export messages to Object Storage

Receive message

• The data field of published messages is Base64-encoded and will be decoded upon delivery.
• Messages are uploaded to the bucket as multipart files.

caution

Multipart uploads may remain incomplete due to errors or cancellations and might not appear in the console.
To prevent storage accumulation, configure lifecycle rules to delete incomplete multipart uploads.

• Learn more about Object Storage lifecycle configuration
• Learn more about AbortIncompleteMultipartUpload (AWS)

Object Storage file upload example

Object Storage file upload example

info

For Object Storage subscriptions, the message body (data) must be included when publishing.
Only the message content (data) is stored in files. Attributes (attributes) are not stored.

Export channel

When an Object Storage subscription is created, an export channel is automatically activated to send messages to the bucket.
(*Enabling/disabling the export channel is currently supported only through the console.)

Export deactivation policy

If the export channel is disabled, delivery to Object Storage stops.
However, messages remaining at the time of deactivation may still be uploaded via multipart.

caution

The export channel may be automatically disabled if the bucket is missing or if permission issues occur.
Follow these steps to re-enable:

1. If the subscription status becomes InvalidBucket or Unauthorized, the export channel is disabled.
   • InvalidBucket: Create a new bucket and update the subscription’s bucket info.
   • Unauthorized: Change the bucket or update bucket permissions.
2. After resolving the issue, verify that the subscription status returns to Active.
3. Go to the subscription detail page and click [Start export] to reactivate the channel.