# Send SMS & Receive DLRs Using Spring Boot
URL: /docs/recipes/send-sms-spring-boot

> Build a production-ready Spring Boot 3 service to dispatch transactional SMS and an HMAC-verified controller to ingest delivery reports.

Difficulty: Intermediate | Duration: 7 min | Language: Java

## Step 1: 1. Configure Application Properties (`src/main/resources/application.properties`)

Store your gateway credentials in `application.properties` (or `application.yml`). Use your `sk_test_...` key for local development and inject `sk_live_...` secrets via environment variables in production.

```properties
# SMS Pro Gateway Configuration
smspro.base-url=https://api.smspro.com
smspro.api-key=${SMSPRO_API_KEY:sk_test_948f293048a1b2c3d4e5f60718}
smspro.webhook-secret=${SMSPRO_WEBHOOK_SECRET:whsec_38f9024a1b2c3d4e5f60718a}
```

## Step 2: 2. Define Immutable Java Records (DTOs) (`src/main/java/com/example/sms/dto/SmsDtos.java`)

Define clean, immutable Java records matching the SMS Pro REST request, response, and delivery report payload specifications.

```java
package com.example.sms.dto;

import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
import java.util.List;

public class SmsDtos {

    public record SendSmsRequest(
        String to,
        String senderId,
        String message
    ) {}

    @JsonIgnoreProperties(ignoreUnknown = true)
    public record SendSmsResponse(
        String status,
        String message,
        JobData data
    ) {
        public record JobData(
            String jobId,
            String messageId,
            String status,
            int segmentCount,
            int totalUnits
        ) {}
    }

    @JsonIgnoreProperties(ignoreUnknown = true)
    public record DlrWebhookEvent(
        String messageId,
        String providerMessageId,
        String to,
        String status,
        String deliveredAt,
        String gateway,
        String raw
    ) {}
}
```

## Step 3: 3. Build the SmsProClient Service (`src/main/java/com/example/sms/service/SmsProClient.java`)

Use Spring Boot 3&apos;s modern `RestClient` to dispatch SMS. Every mutating request automatically attaches a unique `Idempotency-Key` (UUID v4) to prevent duplicate charges or accidental re-sends.

```java
package com.example.sms.service;

import com.example.sms.dto.SmsDtos.SendSmsRequest;
import com.example.sms.dto.SmsDtos.SendSmsResponse;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.http.MediaType;
import org.springframework.stereotype.Service;
import org.springframework.web.client.RestClient;

import java.util.UUID;

@Service
public class SmsProClient {

    private static final Logger log = LoggerFactory.getLogger(SmsProClient.class);
    private final RestClient restClient;

    public SmsProClient(
        @Value("${smspro.base-url}") String baseUrl,
        @Value("${smspro.api-key}") String apiKey
    ) {
        this.restClient = RestClient.builder()
            .baseUrl(baseUrl)
            .defaultHeader("X-Api-Key", apiKey)
            .defaultHeader("Content-Type", MediaType.APPLICATION_JSON_VALUE)
            .build();
    }

    /**
     * Dispatches a single transactional SMS with automatic idempotency protection.
     */
    public SendSmsResponse.JobData sendTransactionalSms(String to, String senderId, String message) {
        String idempotencyKey = UUID.randomUUID().toString();
        log.info("Dispatching SMS to {} via senderId {} (IdempotencyKey: {})", to, senderId, idempotencyKey);

        SendSmsResponse response = restClient.post()
            .uri("/api/v1/public/sms/send")
            .header("Idempotency-Key", idempotencyKey)
            .body(new SendSmsRequest(to, senderId, message))
            .retrieve()
            .body(SendSmsResponse.class);

        if (response != null && response.data() != null) {
            log.info("SMS queued successfully: messageId={}, jobId={}", 
                response.data().messageId(), response.data().jobId());
            return response.data();
        }

        throw new IllegalStateException("Failed to queue SMS: Empty response from SMS Pro gateway");
    }
}
```

## Step 4: 4. Implement the Verified DLR Webhook Controller (`src/main/java/com/example/sms/controller/DlrWebhookController.java`)

Expose an HTTP `POST` endpoint at `/api/v1/webhooks/smspro`. Read `X-SmsPro-Signature` as `t=<unix>,v1=<hex>`, sign `timestamp.rawBody`, and compare equal-length digests.

```java
package com.example.sms.controller;

import com.example.sms.dto.SmsDtos.DlrWebhookEvent;
import com.fasterxml.jackson.databind.ObjectMapper;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.*;

import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import java.nio.charset.StandardCharsets;
import java.security.MessageDigest;
import java.util.HexFormat;

@RestController
@RequestMapping("/api/v1/webhooks")
public class DlrWebhookController {

    private static final Logger log = LoggerFactory.getLogger(DlrWebhookController.class);
    private final String webhookSecret;
    private final ObjectMapper objectMapper;

    public DlrWebhookController(
        @Value("${smspro.webhook-secret}") String webhookSecret,
        ObjectMapper objectMapper
    ) {
        this.webhookSecret = webhookSecret;
        this.objectMapper = objectMapper;
    }

    @PostMapping("/smspro")
    public ResponseEntity<String> handleDlrWebhook(
        @RequestHeader(value = "X-SmsPro-Signature", required = false) String signatureHeader,
        @RequestBody byte[] rawPayload
    ) {
        if (signatureHeader == null || !isValidSignature(rawPayload, signatureHeader)) {
            log.warn("Rejected webhook: Invalid or missing X-SmsPro-Signature");
            return ResponseEntity.status(HttpStatus.UNAUTHORIZED).body("Invalid signature");
        }

        try {
            DlrWebhookEvent event = objectMapper.readValue(rawPayload, DlrWebhookEvent.class);
            log.info("Received verified DLR: messageId={}, status={}",
                event.messageId(), event.status());

            // TODO: Update your internal database status (e.g. orderRepository.markSmsDelivered())

            return ResponseEntity.ok("ACK");
        } catch (Exception e) {
            log.error("Failed to parse verified webhook payload", e);
            return ResponseEntity.status(HttpStatus.BAD_REQUEST).body("Malformed payload");
        }
    }

    private boolean isValidSignature(byte[] payload, String signatureHeader) {
        try {
            int comma = signatureHeader.indexOf(',');
            int tMark = signatureHeader.indexOf("t=");
            int vMark = signatureHeader.indexOf("v1=");
            if (tMark < 0 || vMark < 0 || comma < 0) return false;
            String timestamp = signatureHeader.substring(tMark + 2, comma).trim();
            String expected = signatureHeader.substring(vMark + 3).trim();
            String signed = timestamp + "." + new String(payload, StandardCharsets.UTF_8);
            Mac mac = Mac.getInstance("HmacSHA256");
            mac.init(new SecretKeySpec(webhookSecret.getBytes(StandardCharsets.UTF_8), "HmacSHA256"));
            String computedHex = HexFormat.of().formatHex(mac.doFinal(signed.getBytes(StandardCharsets.UTF_8)));
            byte[] left = computedHex.getBytes(StandardCharsets.UTF_8);
            byte[] right = expected.getBytes(StandardCharsets.UTF_8);
            if (left.length != right.length) return false;
            return MessageDigest.isEqual(left, right);
        } catch (Exception ex) {
            log.error("Error computing HMAC-SHA256 signature", ex);
            return false;
        }
    }
}
```