Customizing email and SMS providers

Edit online

You can customize the email sender and the SMS provider for the IBM® Verify notification messages.

Before you begin

Customers that want to integrate their own SMS provider for IBM Verify OTP notifications must configure an external webhook endpoint that accepts POST requests from IBM Verify.

External webhook setup requirements
  • The external SMS provider must expose an HTTP POST webhook endpoint to receive OTP notification requests from IBM Verify.
  • The endpoint must immediately queue requests and return an HTTP response.
Sample JSON request payload
{
  "destinationPhoneNumber": "18005551212",
  "content": "Your passcode is 6439-123456. It expires in 5 minutes.",
  "category": "OTP",
  "language": "en-US",
  "otp": "123456",
  "correlation": "6439",
  "expiry": 5
}
Field-level descriptions
destinationPhoneNumber
The recipient’s phone number in E.164 format.
content
The complete SMS text that is shown to the user.
category
OTP
language
The locale or language code, for example en-US.
otp
The one-time passcode value.
correlation
The ID to correlate OTP with a verification flow; typically shown in message.
expiry
The validity duration in minutes.
Webhook response requirements
202 Accepted
Request successfully queued.
400 Bad Request
Payload format invalid.
500 Internal Server Error
Provider unable to process.
Example of a success response
{
"status": "accepted",
"statusMessage": "Message accepted by provider"
}
Example of a failure response
{
"status": "failed",
"statusMessage": "The destination phone number is invalid."
}

About this task

IBM is the default email sender and SMS provider for Verify.

Procedure

  1. Navigate to Global configuration > Communication and select the Senders tab.
  2. To change the email sender, click the pencil icon on the Email tile.
    1. Change the default values for the following email options.
      Table 1.

      The table describes the attributes for email notifications.
      Attribute Description
      From sender address Change this field to reflect the email address that you want listed as the sender of the notification.
      From email name Change this field to reflect the person or organization that is sending the notification. For example, your company.
    2. Optional: Select the Use custom SMTP email server checkbox.
      For your custom SMTP server, specify the following information:
      • SMTP host
      • Port
      • Username
      • Password
      • Select the connection protocol, either TLS or SSL.
    3. Click Save.
  3. If your tenant is using IBM SMS services, and you want to change the SMS sender ID, click the pencil icon on the SMS Provider tile.
    You can modify the attribute to reflect your company or organization.
    1. Change the default value for the following option.
      Table 2.

      The table describes the attribute for SMS notifications.
      Attribute Description
      Alphanumeric sender ID Change this field to reflect the alphanumeric identifier (A-Z, a-z, 0-9) that identifies the sender of the message. The value must start with an alphabetic character, cannot include spaces or special characters, and has a maximum length of 11 characters.
      Note: Verify does not support SMS messaging.
    2. Click Save changes.
  4. If your tenant is not using IBM SMS services, and you want to use an external SMS provider, click Add external SMS Provider on the SMS Provider tile.
    1. Provide a name for the SMS provider.
      You can also specify an owner and email contact information.
    2. Specify the request URL.
      The URL points to the external SMS provider endpoint that the Notification Service calls to send an SMS.
    3. Select the type of authentication.
      Basic
      Specify the username and password.
      Header
      Specify the header name and authentication secret. If the secret is case-sensitive, select the Sensitive checkbox.
      None
      No authentication information is needed.
      OAuth
      Specify the token endpoint. Select whether the client secret is post or basic. Enter the client ID and secret.
      Note: Client post indicates that the secret is stored as an attribute. Client basic indicates that the secret is stored in the header.
      JSON Web Token (JWT)
      Specify the HTTP header value, Sub claim, Maximum valid lifetime of the JWT, and Signing algorithm. If you want, you can also specify a JWT header value prefix, a JWT header keys, and claim names.
      Mutual TLS (mTLS)
      Specify the MTLS certificate label.
    4. Click Save.
      The SMS provider is created, but disabled by default.
    5. Test whether your tenant is connected to you SMS provider, click Test connection.
      You can send a test payload to your SMS provider to test the connection.
    6. After a successful connection test and when you are ready to use your external SMS provider, click the Configuration toggle to enable it.
    7. Optional: To check on the status of your SMS provider, click View health stats.
      The health status provides a connection summary and a connection history and statistics for the URL of the SMS provider